# HG changeset patch # User František Kučera # Date 1389392488 -3600 # Node ID eb3676c6929b133cabb94181ed87729978275800 # Parent 016836529e6cdfc7d8c58446a793d91ad01b8e31 more JavaDoc diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/CLIOptions.java --- 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 databaseNameToTest = new HashSet<>(); + private Set 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 getDatabaseNameToTest() { - return databaseNameToTest; + public Set getDatabaseNamesToTest() { + return databaseNamesToTest; } - public void addDatabaseNameToTest(String databaseNameToTest) { - this.databaseNameToTest.add(databaseNameToTest); + public void addDatabaseNamesToTest(String databaseNameToTest) { + this.databaseNamesToTest.add(databaseNameToTest); } public SQLCommand getSQLCommand() { diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/CLIParser.java --- 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); diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/CLIStarter.java --- 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 diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/ColorfulPrintWriter.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/DatabaseConnection.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/InfoLister.java --- 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 data = new ArrayList<>(); - for (String dbName : options.getDatabaseNameToTest()) { + for (String dbName : options.getDatabaseNamesToTest()) { data.add(testConnection(dbName)); } diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/Parameter.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/SQLCommand.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNamed.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/SQLCommandNumbered.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/SQLType.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/batch/Batch.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/configuration/Configuration.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/configuration/ConfigurationProvider.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/configuration/DatabaseDefinition.java --- 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); diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/configuration/FormatterDefinition.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/configuration/Properties.java --- 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 @@ *

List of configurables.

* *

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.

+ * look into defaults. Methods also accept defaultValue parameter – is used if property is nof found + * even in default properties.

* *

Typical use:

*
    diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractFormatter.java --- 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; /** + *
      + *
    1. ensures integrity – if methods are called in correct order and context
      2. + *
    2. provides default implmentations of methods that does not produce any output for given + * events
      3. + *
    * * @author Ing. František Kučera (frantovo.cz) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/AbstractXmlFormatter.java --- 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; /** + *

    + * Provides helper methods for printing pretty intended and optionally colorful (syntax highlighted) + * XML output. + *

    + * + *

    + * Must be used with care – bad usage can lead to invalid XML (e.g. using undeclared namespaces). + *

    * * @author Ing. František Kučera (frantovo.cz) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/Formatter.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/FormatterContext.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularFormatter.java --- 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; /** + *

    Prints human-readable output – tables of result sets and text messages with update counts.

    + * + *

    Longer values might break the table – overflow the cells – see alternative tabular formatters + * and the {@linkplain #PROPERTY_TRIM} property.

    * * @author Ing. František Kučera (frantovo.cz) + * @see TabularPrefetchingFormatter + * @see TabularWrappingFormatter */ public class TabularFormatter extends AbstractFormatter { diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularPrefetchingFormatter.java --- 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; /** + *

    * Prefetches whole result set and computes column widths. Whole table is flushed at once in * {@linkplain #writeEndResultSet()}. + *

    * - * Long values will not overflow the cells, but whole result set must be loaded into memory. + *

    + * Long values will not overflow the cells, but whole result set must be loaded into the memory. + *

    * * @author Ing. František Kučera (frantovo.cz) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/TabularWrappingFormatter.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/XhtmlFormatter.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/formatting/XmlFormatter.java --- 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; /** + *

    Prints machine-readable output – XML document containing resultsets and updates count. Good + * choice for further processing – e.g. XSL transformation.

    + * + *

    TODO: XSD

    * * @author Ing. František Kučera (frantovo.cz) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/logging/ColorfulConsoleFormatter.java --- 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) */ diff -r 016836529e6c -r eb3676c6929b java/sql-dk/src/info/globalcode/sql/dk/logging/LoggerInitializer.java --- 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/… */ }