From 4471ce1f6f61f75fa8ffa3629861a97f101d5235 Mon Sep 17 00:00:00 2001
From: James Ahlborn <jtahlborn@yahoo.com>
Date: Sat, 13 Jun 2009 20:46:21 +0000
Subject: [PATCH] update docs

git-svn-id: https://svn.code.sf.net/p/jackcess/code/jackcess/trunk@398 f203690c-595d-4dc9-a70b-905162fa7fd2
---
 .../jackcess/Database.java                    |  2 +-
 .../jackcess/query/AppendQuery.java           |  3 ++
 .../jackcess/query/BaseSelectQuery.java       |  4 +-
 .../jackcess/query/CrossTabQuery.java         |  3 ++
 .../jackcess/query/DataDefinitionQuery.java   |  2 +-
 .../jackcess/query/DeleteQuery.java           |  3 ++
 .../jackcess/query/MakeTableQuery.java        |  5 ++-
 .../jackcess/query/PassthroughQuery.java      |  3 +-
 .../jackcess/query/Query.java                 | 41 +++++++++++++++++--
 .../jackcess/query/QueryFormat.java           |  2 +
 .../jackcess/query/SelectQuery.java           |  3 ++
 .../jackcess/query/UnionQuery.java            |  3 +-
 .../jackcess/query/UpdateQuery.java           |  3 ++
 13 files changed, 66 insertions(+), 11 deletions(-)

diff --git a/src/java/com/healthmarketscience/jackcess/Database.java b/src/java/com/healthmarketscience/jackcess/Database.java
index 0416a7f..71380ce 100644
--- a/src/java/com/healthmarketscience/jackcess/Database.java
+++ b/src/java/com/healthmarketscience/jackcess/Database.java
@@ -618,7 +618,7 @@ public class Database
   }
 
   /**
-   * Finds all the relationships in the database between the given tables.
+   * Finds all the queries in the database.
    */
   public List<Query> getQueries()
     throws IOException
diff --git a/src/java/com/healthmarketscience/jackcess/query/AppendQuery.java b/src/java/com/healthmarketscience/jackcess/query/AppendQuery.java
index ef4d1a1..3a216e8 100644
--- a/src/java/com/healthmarketscience/jackcess/query/AppendQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/AppendQuery.java
@@ -33,6 +33,9 @@ import static com.healthmarketscience.jackcess.query.QueryFormat.*;
 
 
 /**
+ * Concrete Query subclass which represents an append query, e.g.:
+ * {@code INSERT INTO <table> VALUES (<values>)}
+ * 
  * @author James Ahlborn
  */
 public class AppendQuery extends BaseSelectQuery 
diff --git a/src/java/com/healthmarketscience/jackcess/query/BaseSelectQuery.java b/src/java/com/healthmarketscience/jackcess/query/BaseSelectQuery.java
index 30cbd5d..272baca 100644
--- a/src/java/com/healthmarketscience/jackcess/query/BaseSelectQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/BaseSelectQuery.java
@@ -27,14 +27,14 @@ King of Prussia, PA 19406
 
 package com.healthmarketscience.jackcess.query;
 
-import java.util.ArrayList;
-import java.util.Iterator;
 import java.util.List;
 
 import static com.healthmarketscience.jackcess.query.QueryFormat.*;
 
 
 /**
+ * Base class for queries which represent some form of SELECT statement.
+ * 
  * @author James Ahlborn
  */
 public abstract class BaseSelectQuery extends Query 
diff --git a/src/java/com/healthmarketscience/jackcess/query/CrossTabQuery.java b/src/java/com/healthmarketscience/jackcess/query/CrossTabQuery.java
index e750998..3fd6bf6 100644
--- a/src/java/com/healthmarketscience/jackcess/query/CrossTabQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/CrossTabQuery.java
@@ -33,6 +33,9 @@ import static com.healthmarketscience.jackcess.query.QueryFormat.*;
 
 
 /**
+ * Concrete Query subclass which represents a crosstab/pivot query, e.g.:
+ * {@code TRANSFORM <expr> SELECT <query> PIVOT <expr>}
+ * 
  * @author James Ahlborn
  */
 public class CrossTabQuery extends BaseSelectQuery 
diff --git a/src/java/com/healthmarketscience/jackcess/query/DataDefinitionQuery.java b/src/java/com/healthmarketscience/jackcess/query/DataDefinitionQuery.java
index 282a6a0..16937b3 100644
--- a/src/java/com/healthmarketscience/jackcess/query/DataDefinitionQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/DataDefinitionQuery.java
@@ -31,7 +31,7 @@ import java.util.List;
 
 
 /**
- * SQL query which represents a DDL query.
+ * Concrete Query subclass which represents a DDL query.
  * 
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/query/DeleteQuery.java b/src/java/com/healthmarketscience/jackcess/query/DeleteQuery.java
index b2d0bc9..4f42b82 100644
--- a/src/java/com/healthmarketscience/jackcess/query/DeleteQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/DeleteQuery.java
@@ -31,6 +31,9 @@ import java.util.List;
 
 
 /**
+ * Concrete Query subclass which represents a delete query, e.g.:
+ * {@code DELETE * FROM <table> WHERE <expression>}
+ *
  * @author James Ahlborn
  */
 public class DeleteQuery extends BaseSelectQuery 
diff --git a/src/java/com/healthmarketscience/jackcess/query/MakeTableQuery.java b/src/java/com/healthmarketscience/jackcess/query/MakeTableQuery.java
index c7dbc4b..2144197 100644
--- a/src/java/com/healthmarketscience/jackcess/query/MakeTableQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/MakeTableQuery.java
@@ -29,10 +29,11 @@ package com.healthmarketscience.jackcess.query;
 
 import java.util.List;
 
-import static com.healthmarketscience.jackcess.query.QueryFormat.*;
-
 
 /**
+ * Concrete Query subclass which represents an table creation query, e.g.:
+ * {@code SELECT <query> INTO <newTable>}
+ * 
  * @author James Ahlborn
  */
 public class MakeTableQuery extends BaseSelectQuery 
diff --git a/src/java/com/healthmarketscience/jackcess/query/PassthroughQuery.java b/src/java/com/healthmarketscience/jackcess/query/PassthroughQuery.java
index fc2fc61..cb18090 100644
--- a/src/java/com/healthmarketscience/jackcess/query/PassthroughQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/PassthroughQuery.java
@@ -31,7 +31,8 @@ import java.util.List;
 
 
 /**
- * SQL query which represents a query which will be executed via ODBC.
+ * Concrete Query subclass which represents a query which will be executed via
+ * ODBC.
  * 
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/query/Query.java b/src/java/com/healthmarketscience/jackcess/query/Query.java
index acc0954..0f5dfc5 100644
--- a/src/java/com/healthmarketscience/jackcess/query/Query.java
+++ b/src/java/com/healthmarketscience/jackcess/query/Query.java
@@ -44,6 +44,10 @@ import static com.healthmarketscience.jackcess.query.QueryFormat.*;
 
 
 /**
+ * Base class for classes which encapsulate information about an Access query.
+ * The {@link #toSQLString()} method can be used to convert this object into
+ * the actual SQL string which this query data represents.
+ * 
  * @author James Ahlborn
  */
 public abstract class Query 
@@ -103,14 +107,23 @@ public abstract class Query
     }
   }
 
+  /**
+   * Returns the name of the query.
+   */
   public String getName() {
     return _name;
   }
 
+  /**
+   * Returns the type of the query.
+   */
   public Type getType() {
     return _type;
   }
 
+  /**
+   * Returns the unique object id of the query.
+   */
   public int getObjectId() {
     return _objectId;
   }
@@ -119,6 +132,10 @@ public abstract class Query
     return getType().getObjectFlag();
   }
 
+  /**
+   * Returns the rows from the system query table from which the query
+   * information was derived.
+   */
   public List<Row> getRows() {
     return _rows;
   }
@@ -353,6 +370,9 @@ public abstract class Query
     return true;
   }
 
+  /**
+   * Returns the actual SQL string which this query data represents.
+   */
   public String toSQLString() 
   {
     StringBuilder builder = new StringBuilder();
@@ -379,6 +399,17 @@ public abstract class Query
     return ToStringBuilder.reflectionToString(this);
   }
 
+  /**
+   * Creates a concrete Query instance from the given query data.
+   *
+   * @param objectFlag the flag indicating the type of the query
+   * @param name the name of the query
+   * @param rows the rows from the system query table containing the data
+   *             describing this query
+   * @param objectId the unique object id of this query
+   *
+   * @return a Query instance for the given query data
+   */
   public static Query create(int objectFlag, String name, List<Row> rows, 
                              int objectId)
   {
@@ -525,7 +556,7 @@ public abstract class Query
     return builder;
   }
 
-  private static class UnknownQuery extends Query
+  private static final class UnknownQuery extends Query
   {
     private final int _objectFlag;
 
@@ -547,7 +578,11 @@ public abstract class Query
     }
   }
 
-  public static class Row
+  /**
+   * Struct containing the information from a single row of the system query
+   * table.
+   */
+  public static final class Row
   {
     public final Byte attribute;
     public final String expression;
@@ -674,7 +709,7 @@ public abstract class Query
     }
   }
 
-  private static class Join
+  private static final class Join
   {
     public final List<String> tables = new ArrayList<String>();
     public boolean isJoin;
diff --git a/src/java/com/healthmarketscience/jackcess/query/QueryFormat.java b/src/java/com/healthmarketscience/jackcess/query/QueryFormat.java
index d54a567..4b1fd92 100644
--- a/src/java/com/healthmarketscience/jackcess/query/QueryFormat.java
+++ b/src/java/com/healthmarketscience/jackcess/query/QueryFormat.java
@@ -35,6 +35,8 @@ import com.healthmarketscience.jackcess.DataType;
 import org.apache.commons.lang.SystemUtils;
 
 /**
+ * Constants used by the query data parsing.
+ * 
  * @author James Ahlborn
  */
 public class QueryFormat 
diff --git a/src/java/com/healthmarketscience/jackcess/query/SelectQuery.java b/src/java/com/healthmarketscience/jackcess/query/SelectQuery.java
index c639286..3efd029 100644
--- a/src/java/com/healthmarketscience/jackcess/query/SelectQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/SelectQuery.java
@@ -31,6 +31,9 @@ import java.util.List;
 
 
 /**
+ * Concrete Query subclass which represents a select query, e.g.:
+ * {@code SELECT <columns> FROM <tables> WHERE <expression>}
+ * 
  * @author James Ahlborn
  */
 public class SelectQuery extends BaseSelectQuery 
diff --git a/src/java/com/healthmarketscience/jackcess/query/UnionQuery.java b/src/java/com/healthmarketscience/jackcess/query/UnionQuery.java
index 3534a70..cd75906 100644
--- a/src/java/com/healthmarketscience/jackcess/query/UnionQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/UnionQuery.java
@@ -33,7 +33,8 @@ import static com.healthmarketscience.jackcess.query.QueryFormat.*;
 
 
 /**
- * SQL query which represents a UNION query.
+ * Concrete Query subclass which represents a UNION query, e.g.:
+ * {@code SELECT <query1> UNION SELECT <query2>}
  * 
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/query/UpdateQuery.java b/src/java/com/healthmarketscience/jackcess/query/UpdateQuery.java
index b94d5ce..747a9b3 100644
--- a/src/java/com/healthmarketscience/jackcess/query/UpdateQuery.java
+++ b/src/java/com/healthmarketscience/jackcess/query/UpdateQuery.java
@@ -33,6 +33,9 @@ import static com.healthmarketscience.jackcess.query.QueryFormat.*;
 
 
 /**
+ * Concrete Query subclass which represents a row update query, e.g.:
+ * {@code UPDATE <table> SET <newValues>}
+ * 
  * @author James Ahlborn
  */
 public class UpdateQuery extends Query 
-- 
2.39.5