You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by dl...@locus.apache.org on 2000/09/22 21:46:54 UTC

cvs commit: xml-xalan/java/src/org/apache/xalan/lib/sql package.html Column.java ColumnAttribute.java ColumnData.java ColumnHeader.java Row.java RowSet.java StreamableNode.java XConnection.java XStatement.java

dleslie     00/09/22 12:46:50

  Modified:    java/src/org/apache/xalan/lib/sql Column.java
                        ColumnAttribute.java ColumnData.java
                        ColumnHeader.java Row.java RowSet.java
                        StreamableNode.java XConnection.java
                        XStatement.java
  Added:       java/src/org/apache/xalan/lib/sql package.html
  Log:
  1. Added XConnection constructors so can use any of DriverManager
  getConnection() methods: just a dbURL, dbURL with protocol,
  dbURL with userID and password.
  2. Updated the Javadoc comments and added a package-level doc.
  
  Revision  Changes    Path
  1.2       +14 -14    xml-xalan/java/src/org/apache/xalan/lib/sql/Column.java
  
  Index: Column.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/Column.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- Column.java	2000/08/07 02:48:12	1.1
  +++ Column.java	2000/09/22 19:46:17	1.2
  @@ -9,8 +9,7 @@
   import java.sql.ResultSetMetaData;
   
   /**
  - * This class represents a column node from a row in a JDBC-accessed 
  - * database.
  + * Represents a col node from a row node.
    */
   public class Column extends StreamableNode
   {
  @@ -29,7 +28,7 @@
     }
     
     /**
  -   * The parent of a document is null.
  +   * The parent of col is #Document (represented by XStatement).
      */
     public Document getOwnerDocument()
     {
  @@ -37,7 +36,7 @@
     }
     
     /**
  -   * Return "#Document".
  +   * Return "col".
      */
     public String getNodeName()
     {
  @@ -45,7 +44,7 @@
     }
         
     /**
  -   * Return the document element node.
  +   * Return the col text node (the column value).
      */
     public Node getFirstChild()
     {
  @@ -59,7 +58,8 @@
     }
     
     /**
  -   * This always returns null.
  +   * Return the next col element for the current row.
  +   * @return a Column node or null.
      */
     public Node getNextSibling()
     {
  @@ -71,7 +71,7 @@
     }
     
     /**
  -   * The parent node of document is always null.
  +   * The parent node of col is a row.
      */
     public Node getParentNode()
     {
  @@ -81,8 +81,9 @@
     }
     
     /**
  -   * Tell if there are any children of the document, 
  -   * which is always true.
  +   * Tell if there are any children of col, 
  +   * which is always true. I.e., col contains a text node
  +   * with a textual representation of the column value.
      */
     public boolean            hasChildNodes()
     {
  @@ -90,12 +91,11 @@
         System.out.println("In Column.hasChildNodes");
       return true;
     }
  -  
  +  /**
  +   * Return the metadata for this column.
  +   */
     public NamedNodeMap       getAttributes()
     {
       return m_parent.m_parent.m_columnHeaders[m_columnIndex];
  -  }
  -
  -
  -  
  +  }  
   }
  
  
  
  1.2       +23 -1     xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnAttribute.java
  
  Index: ColumnAttribute.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnAttribute.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ColumnAttribute.java	2000/08/07 02:48:12	1.1
  +++ ColumnAttribute.java	2000/09/22 19:46:19	1.2
  @@ -14,7 +14,29 @@
   import org.apache.xalan.res.XSLTErrorResources;
   
   /**
  - * This class represents a column attribute on a ColumnHeader element.
  + * Represents a column attribute on a column-header element.
  + * Each column-header element can contain any of the following
  + * attributes, depending on the ResultSetMetadata object returned with
  + * the query result set.
  + * <ul>
  + *   <li>column-label</li>
  + *   <li>column-name</li>
  + *   <li>column-display-size</li> 
  + *   <li>column-type</li>
  + *   <li>column-type-name</li>
  + *   <li>precision</li>
  + *   <li>scale</li>
  + *   <li>catalogue-name</li>
  + *   <li>schema-name</li>
  + *   <li>table-name</li>
  + *   <li>case-sensitive</li>
  + *   <li>definitely-writable</li>
  + *   <li>nullable</li>
  + *   <li>signed</li>
  + *   <li>writable</li>
  + *   <li>searchable</li>
  + * </ul>
  + * @see org.apache.xalan.lib.sql.ColumnHeader.
    */
   public class ColumnAttribute extends StreamableNode implements Attr
   {
  
  
  
  1.2       +33 -9     xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnData.java
  
  Index: ColumnData.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnData.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ColumnData.java	2000/08/07 02:48:12	1.1
  +++ ColumnData.java	2000/09/22 19:46:20	1.2
  @@ -12,7 +12,7 @@
   import org.apache.xalan.res.XSLTErrorResources;
   
   /**
  - * This class represents a text node from a Column element.
  + * Represents the col element text node, i.e., the column value.
    */
   public class ColumnData extends StreamableNode implements Text
   {
  @@ -40,6 +40,10 @@
       return null;
     }
   
  +  /**
  +   * Return the value for this col element text node. I.e., return a String representation 
  +   * of the data for this column in the current row.
  +   */
     public String getData()
       throws DOMException
     {
  @@ -62,6 +66,11 @@
         return null;
       }
     }
  +  /**
  +   * Return the value for this col element text node. I.e., return a String representation 
  +   * of the data for this column in the current row.
  +   * Calls @link #getNodeValue() getNodeValue()}.
  +   */
     
     public String getNodeValue()
       throws DOMException
  @@ -80,7 +89,9 @@
       String s = getData();
       return (null != s) ? s.length() : 0;
     }
  -  
  +/**
  + * Not supported.
  + */  
     public String substringData(int offset, 
                                 int count)
       throws DOMException
  @@ -89,12 +100,18 @@
       return null;
     }
     
  + /**
  + * Not supported.
  + */   
     public void appendData(String arg)
       throws DOMException
     {
       error(XSLTErrorResources.ER_FUNCTION_NOT_SUPPORTED);
     }
     
  +/**
  + * Not supported.
  + */    
     public void insertData(int offset, 
                            String arg)
       throws DOMException
  @@ -102,6 +119,9 @@
       error(XSLTErrorResources.ER_FUNCTION_NOT_SUPPORTED);
     }
   
  +  /**
  + * Not supported.
  + */  
     public void deleteData(int offset, 
                            int count)
       throws DOMException
  @@ -109,6 +129,9 @@
       error(XSLTErrorResources.ER_FUNCTION_NOT_SUPPORTED);
     }
   
  +/**
  + * Not supported.
  + */    
     public void replaceData(int offset, 
                             int count, 
                             String arg)
  @@ -116,7 +139,10 @@
     {
       error(XSLTErrorResources.ER_FUNCTION_NOT_SUPPORTED);
     }
  -  
  +
  +/**
  + * Not supported.
  + */    
     public void setData(String data)
       throws DOMException
     {
  @@ -127,7 +153,7 @@
   
     
     /**
  -   * The parent of a document is null.
  +   * The owner of a col text ode is the #Document (represented by XStatement).
      */
     public Document getOwnerDocument()
     {
  @@ -163,7 +189,7 @@
     }
     
     /**
  -   * The parent node of document is always null.
  +   * The parent node of the col text node is the col node.
      */
     public Node               getParentNode()
     {
  @@ -173,8 +199,8 @@
     }
     
     /**
  -   * Tell if there are any children of the document, 
  -   * which is always true.
  +   * Tell if there are any children of the col node, 
  +   * which is always false.
      */
     public boolean            hasChildNodes()
     {
  @@ -182,6 +208,4 @@
         System.out.println("In ColumnData.hasChildNodes");
       return false;
     }
  -
  -
   }
  
  
  
  1.2       +22 -10    xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnHeader.java
  
  Index: ColumnHeader.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/ColumnHeader.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ColumnHeader.java	2000/08/07 02:48:12	1.1
  +++ ColumnHeader.java	2000/09/22 19:46:21	1.2
  @@ -11,7 +11,7 @@
   import org.apache.xalan.res.XSLTErrorResources;
   
   /**
  - * This class represents a ColumnHeader, which represents the metadata 
  + * This class represents a column-header Node, which contains the metadata 
    * for a column.
    */
   public class ColumnHeader extends StreamableNode implements NamedNodeMap
  @@ -31,7 +31,7 @@
     }
   
     /**
  -   * Return "row-set".
  +   * Return "column-header".
      */
     public String getNodeName()
     {
  @@ -39,7 +39,7 @@
     }
     
     /**
  -   * Return the document element node.
  +   * Always returns null.
      */
     public Node               getFirstChild()
     {
  @@ -50,7 +50,8 @@
     }
     
     /**
  -   * This always returns null.
  +   * Returns column-header Node for the next column.
  +   * @return a ColumnHeader Node or null.
      */
     public Node               getNextSibling()
     {
  @@ -83,7 +84,8 @@
     }
     
     /**
  -   * The parent node of document is always null.
  +   * The parent node of a column-header Node is the row-set Node.
  +   * @returns a RowSet.
      */
     public Node               getParentNode()
     {
  @@ -93,8 +95,8 @@
     }
     
     /**
  -   * Tell if there are any children of the document, 
  -   * which is always true.
  +   * Tell if there are any children of the column-header Node, 
  +   * which is always false.
      */
     public boolean            hasChildNodes()
     {
  @@ -102,7 +104,10 @@
         System.out.println("In ColumnHeader.hasChildNodes");
       return false;
     }
  -  
  +
  +  /**
  +   * Return the metadata for this column.
  +   */
     public NamedNodeMap       getAttributes()
     {
       return this;
  @@ -138,6 +143,9 @@
       return m_attributes[pos];
     }
     
  + /**
  +  * Get an attribute by name from the metadata for this column.
  +  */
     public Node getNamedItem(String name)
     {
       if(null == m_attributes)
  @@ -151,6 +159,9 @@
         return null;
     }
       
  + /**
  +  * Get an attribute by index from the metadata for this column.
  +  */
     public Node item(int index)
     {
       if(null == m_attributes)
  @@ -165,6 +176,9 @@
         return null;
     }
   
  + /**
  +  * Get the number of attributes of column metadata attributes.
  +  */  
     public int getLength()
     {
       return ColumnAttribute.NUMBER_ATTRIBUTES;
  @@ -206,7 +220,5 @@
       error(XSLTErrorResources.ER_FUNCTION_NOT_SUPPORTED); 
       return null;
     }
  -
  -
   
   }
  
  
  
  1.3       +8 -8      xml-xalan/java/src/org/apache/xalan/lib/sql/Row.java
  
  Index: Row.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/Row.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- Row.java	2000/08/11 02:57:18	1.2
  +++ Row.java	2000/09/22 19:46:23	1.3
  @@ -11,7 +11,7 @@
   import java.sql.ResultSet;
   
   /**
  - * This class represents a row from a database.  It is used 
  + * This class represents a row from a query result set.  It is used 
    * over and over, and so is certainly not fully DOM complient, 
    * and will result in strange results in the stylesheet if the 
    * user is not carefull.
  @@ -52,7 +52,7 @@
     // ===== Element implementation =====
       
     /**
  -   * The parent of a document is null.
  +   * The parent of a row is #Document represented by XStatement).
      */
     public Document getOwnerDocument()
     {
  @@ -60,7 +60,7 @@
     }
     
     /**
  -   * Return "#Document".
  +   * Return "row".
      */
     public String getNodeName()
     {
  @@ -68,7 +68,7 @@
     }
         
     /**
  -   * Return the document element node.
  +   * Return the first col element for the current row.
      */
     public Node               getFirstChild()
     {
  @@ -82,7 +82,8 @@
     }
     
     /**
  -   * This always returns null.
  +   * Return next row in the row-set. Use the same Row object over and over
  +   * if the row-set is streamable.
      */
     public Node               getNextSibling()
     {
  @@ -144,8 +145,8 @@
     }
     
     /**
  -   * Tell if there are any children of the document, 
  -   * which is always true.
  +   * Tell if the row Node has any children (col Nodes), 
  +   * which should always be true.
      */
     public boolean            hasChildNodes()
     {
  @@ -153,5 +154,4 @@
         System.out.println("In Row.hasChildNodes");
       return (m_childCount > 0);
     }
  -
   }
  
  
  
  1.2       +6 -4      xml-xalan/java/src/org/apache/xalan/lib/sql/RowSet.java
  
  Index: RowSet.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/RowSet.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- RowSet.java	2000/08/07 02:48:12	1.1
  +++ RowSet.java	2000/09/22 19:46:24	1.2
  @@ -9,8 +9,8 @@
   import java.sql.ResultSetMetaData;
   
   /**
  - * This class represents the document element of a virtual 
  - * document that represents a JDBC query.
  + * This class represents the row-set StreamableNode, a "streamable" holder  
  + * for the JDBC query result set.
    */
   public class RowSet extends StreamableNode
   {
  @@ -34,7 +34,9 @@
     }
       
     /**
  -   * Return the document element node.
  +   * The first time the client asks for a column-header element, instantiate an array of ColumnHeaders
  +   * (1 per column), and return the ColumnHeader for the first row.
  +   * @return ColumnHeader Node for first row or null.
      */
     public Node               getFirstChild()
     {
  @@ -95,7 +97,7 @@
     }
     
     /**
  -   * The parent node of document is always null.
  +   * The parent node of row-set is #Document (represented by XStatement).
      */
     public Node               getParentNode()
     {
  
  
  
  1.4       +5 -4      xml-xalan/java/src/org/apache/xalan/lib/sql/StreamableNode.java
  
  Index: StreamableNode.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/StreamableNode.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- StreamableNode.java	2000/08/11 02:57:18	1.3
  +++ StreamableNode.java	2000/09/22 19:46:25	1.4
  @@ -11,7 +11,7 @@
   import org.apache.xpath.DOMOrder;
   
   /**
  - * This is the superclass for all nodes in the Xalan sql package.
  + * This is the superclass for all nodes in the org.apache.xalan.lib.sql package.
    */
   public class StreamableNode extends UnImplNode 
     implements NodeTestFilter, NamedNodeMap, DOMOrder
  @@ -58,7 +58,7 @@
     }
     
     /**
  -   * Return "#Document".
  +   * Return NodeName.
      */
     public String       getLocalName()
     {
  @@ -73,7 +73,9 @@
       return null;
     }
   
  -  /** Returns null. */
  +  /** 
  +   * Returns null. 
  +   */
     public String             getPrefix()
     {
       return null;
  @@ -155,5 +157,4 @@
       // System.out.flush();
       return m_orderIndex;
     }
  -
   }
  
  
  
  1.2       +108 -16   xml-xalan/java/src/org/apache/xalan/lib/sql/XConnection.java
  
  Index: XConnection.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/XConnection.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- XConnection.java	2000/08/07 02:48:12	1.1
  +++ XConnection.java	2000/09/22 19:46:26	1.2
  @@ -4,28 +4,56 @@
   import java.sql.DatabaseMetaData;
   import java.sql.DriverManager;
   import java.sql.SQLException;
  -
  +import java.util.Properties;
  +import org.xml.sax.AttributeList;
  +import org.w3c.dom.Element;
  +import org.w3c.dom.NamedNodeMap;
   import org.w3c.dom.traversal.NodeIterator;
   
   /**
  - * This is an extension for XSLT that allows a stylesheet to 
  - * access JDBC data.
  + * An XSLT extension that allows a stylesheet to
  + * access JDBC data. From the stylesheet perspective,
  + * XConnection provides 3 extension functions: new(), 
  + * query(), and close().
  + * Use new() to call one of XConnection constructors, which
  + * establishes a JDBC driver connection to a data source and 
  + * returns an XConnection object.
  + * Then use the XConnection object query() method to return a 
  + * result set in the form of a row-set element. 
  + * When you have finished working with the row-set, call the
  + * XConnection object close() method to terminate the connection.
    */
   public class XConnection
   { 
     private static final boolean DEBUG = false;
   
     /**
  -   * A database url of the form jdbc:subprotocol:subname.
  +   * A JDBC driver of the form "foo.bar.Driver".
      */
     public String m_driver;
  +
  +  /**
  +   * A database URL of the form jdbc:subprotocol:subname.
  +   */
  +  public String m_dbURL;
     
     /**
  +   * A user ID.
  +   */
  +  public String m_user;
  +
  +  /**
  +   * A password.
  +   */
  +public String m_password;
  +  
  +  /**
      * A list of arbitrary string tag/value pairs as connection 
      * arguments; normally at least a "user" and "password" 
      * property should be included.
      */
  -  public String m_protocol;
  +  
  +  public Properties m_protocol;
     
     /**
      * The JDBC connection.
  @@ -33,22 +61,65 @@
     public Connection m_connection = null;
       
     /**
  -   * Create a SimpleNodeLocator object.
  +   * Create an XConnection object with just a driver and database URL.
  +   * @param driver JDBC driver of the form foo.bar.Driver.
  +   * @param dbURL database URL of the form jdbc:subprotocol:subname.
      */
  -  public XConnection(String driver, String protocol)
  +  public XConnection(String driver, String dbURL)
     {
       super();
  -    init(driver, protocol);
  +	
  +    init(driver, dbURL, null, null, null, 1);
     }
  +  /**
  +   * Create an XConnection object with user ID and password.
  +   * @param driver JDBC driver of the form foo.bar.Driver.
  +   * @param dbURL database URL of the form jdbc:subprotocol:subname.
  +   * @param user user ID.
  +   * @param password connection password.
  +   */
  +  
  +  public XConnection(String driver, String dbURL, String user, String password)
  +   {
  +    super();
  +    init(driver, dbURL, user, password, null, 3);
  +  }
     
     /**
  +   * Create an XConnection object with a connection protocol
  +   * @param driver JDBC driver of the form foo.bar.Driver.
  +   * @param dbURL database URL of the form jdbc:subprotocol:subname.
  +   * @param protocol list of string tag/value connection arguments,
  +   * normally including at least "user" and "password".
  +   */
  +  public XConnection(String driver, String dbURL, Element protocolElem)
  +  {
  +    super();	
  +    init(driver, dbURL, null, null, protocolElem, 2);
  +  }  
  +  /**
      * Initialize.
      */
  -  private void init(String driver, String protocol)
  +  private void init(String driver, String dbURL, String user, 
  +					String password,  Element protocolElem, int getConnectionArgs)
     {
       m_driver = driver;
  -    m_protocol = protocol;
  -    connect(driver, protocol);
  +    m_dbURL = dbURL;
  +	m_user = user;
  +	m_password = password;
  +	
  +	if(protocolElem == null)
  +	  m_protocol = null;
  +	else
  +	{
  +	  m_protocol = new Properties();
  +	  NamedNodeMap atts = protocolElem.getAttributes();
  +      for (int i = 0; i < atts.getLength(); i++)
  +      {	  
  +        m_protocol.put(atts.item(i).getNodeName(), atts.item(i).getNodeValue());
  +      }
  +	}	
  +	connect(driver, dbURL, user, password, m_protocol, getConnectionArgs);
     }
     
     /**
  @@ -58,20 +129,31 @@
      * connection arguments; normally at least a "user" and "password" 
      * property should be included.
      */
  -  public void connect(String driver, String protocol) 
  +  public void connect(String driver, String dbURL, String user,
  +					  String password, Properties protocol, int getConnectionArgs) 
     {    
    try 
       {      
         // The driver is installed by loading its class.
         Class.forName(driver).newInstance();
   
  -      m_connection = DriverManager.getConnection(protocol);
  -      
  +      // Use the appropriate getConnection() method.
  +	  switch(getConnectionArgs)
  +	  {
  +	    case 1:		 
  +	    m_connection = DriverManager.getConnection(dbURL);
  +		break;
  +	    case 2:
  +		m_connection = DriverManager.getConnection(dbURL, protocol);
  +		break;
  +        case 3:
  +		m_connection = DriverManager.getConnection(dbURL, user, password);
  +	 }
         /*
         We could also turn autocommit off by putting
         ;autocommit=false on the URL.
         */
         m_connection.setAutoCommit(false);
  -      
			DatabaseMetaData dma = m_connection.getMetaData ();
  +      
	  DatabaseMetaData dma = m_connection.getMetaData ();
   
         if(DEBUG)
         {
  @@ -88,6 +170,13 @@
       }
     }
     
  + /**
  +  * Execute a query statement by instantiating an {@link org.apache.xalan.lib.sql.XStatement XStatement}
  +  * object. The XStatement executes the query, and uses the result set to create a 
  +  * {@link org.apache.xalan.lib.sql.RowSet RowSet}, a row-set element.
  +  * @param queryString the SQL query.
  +  * @return XStatement implements NodeIterator.
  +  */
     public NodeIterator query(String queryString)
       throws SQLException
     {
  @@ -95,7 +184,10 @@
       return new XStatement(this, queryString);
     }
     
  -  public void close()
  +  /*
  +   * Close the connection to the data source.
  +   */
  +   public void close()
       throws SQLException
     {
       if(DEBUG)
  
  
  
  1.3       +22 -8     xml-xalan/java/src/org/apache/xalan/lib/sql/XStatement.java
  
  Index: XStatement.java
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/sql/XStatement.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- XStatement.java	2000/08/11 02:57:18	1.2
  +++ XStatement.java	2000/09/22 19:46:27	1.3
  @@ -14,8 +14,9 @@
   import org.apache.xalan.res.XSLTErrorResources;
   
   /**
  - * This class represents a JDBC query statement, and also
  - * acts as both a NodeIterator and the Document node.
  + * Represents a JDBC query statement. Also acts as both a
  + * NodeIterator and the Document node for the row-set representation 
  + * of the query result set.
    */
   public class XStatement extends StreamableNode 
     implements NodeIterator, ContextNodeList, Cloneable
  @@ -54,13 +55,23 @@
     static final String S_ROWNAME = "row";
     static final String S_COLUMNNAME = "col";
     
  + /**
  +  * The {@link org.apache.xalan.lib.sql.XConnection#query(java.lang.String) XConnection query()}
  +  * method uses this constructor to execute a SQL query statement. When instantiated,
  +  * XStatement executes the query and creates a 
  +  * {@link org.apache.xalan.lib.sql.RowSet RowSet}, a row-set element associated with the query
  +  * result set.
  +  * @param connection the XConnection object that calls this constructor.
  +  * @param queryString the SQL query.
  +  * 
  +  */
     public XStatement(XConnection connection, String queryString)
       throws SQLException
     {
       super(null);
       if(DEBUG)
         System.out.println("In XStatement constructor");
  -    // The SQL statement which let's us execute commands against the connection.
  +    // The SQL statement which lets us execute commands against the connection.
       m_xconnection = connection;
       m_statement = m_xconnection.m_connection.createStatement();
       m_queryString = queryString;
  @@ -79,7 +90,8 @@
     // ============== NodeIterator interface =============
     
     /**
  -   *  The root node of the Iterator, as specified when it was created.
  +   *  The XStatement object is the NodeIterator root.
  +   * @return itself.
      */
     public Node getRoot()
     {
  @@ -103,6 +115,7 @@
   
     /**
      *  The filter used to screen nodes.
  +   * @return null.
      */
     public NodeFilter getFilter()
     {
  @@ -122,6 +135,7 @@
      * a view of the document that has entity reference nodes but no entity 
      * expansion, use the whatToShow flags to show the entity reference node 
      * and set expandEntityReferences to false.
  +   * @return true.
      */
     public boolean getExpandEntityReferences()
     {
  @@ -131,7 +145,9 @@
     }
       
     /**
  -   * Return the document node.
  +   * Return the #Document node (one role the XStatement plays) the first time called; 
  +   * return null thereafter.
  +   * @return this or null.
      */
     public Node nextNode()
       throws DOMException
  @@ -214,7 +230,7 @@
     }
     
     /**
  -   * Return the document element node.
  +   * Return the row-set node.
      */
     public Node               getFirstChild()
     {
  @@ -323,6 +339,4 @@
       XStatement clone = (XStatement)super.clone();
       return clone;
     }
  -
  -
   }
  
  
  
  1.1                  xml-xalan/java/src/org/apache/xalan/lib/sql/package.html
  
  Index: package.html
  ===================================================================
  <html>
    <title>Xalan SQL Extension.</title>
    <body>
      <p>Provides extension functions for connecting to a JDBC data source, executing a query,
      and working incrementally through "streamable" result set.<p>
      <p>XConnection provides three extension functions that you can use in your stylesheet.</p>
      <ol>
        <li><p>new() -- Use one of the XConnection constructors to connect to a data source, and return an XConnection
         object.</p></li>
        <li><p>query() -- Use the XConnection object query() method to return a "streamable" result set in the form of a row-set
         node. Work your way through the row-set one row at a time. The same row element is used over and over again, so you can
         begin "transforming" the row-set before the entire result set has been returned.</p></li>
        <li>close() -- Use the XConnection object close() method to terminate the connection.</li>      
      </ol>
      <p>The query() extension function returns a Document node that contains (as needed) an array of column-header elements, 
      a single row element that is used repeatedly, and an array of col elements. Each column-header element (one per column in the
      row-set) contains an attribute (ColumnAttribute) for each of the column descriptors in the ResultSetMetaData object. 
      Each col element contains a text node with a textual representation of the value for that column in the current row.</p>
      <h2>Example</h2>
      <p>This example displays the result set from a table in a sample InstantDB database.</p>
  <pre>&lt;?xml version="1.0"?&gt;
  &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                  version="1.0"
                  xmlns:sql="org.apache.xalan.lib.sql.XConnection"
                  extension-element-prefixes="sql"&gt;
    &lt;xsl:output method="html" indent="yes"/&gt;
    &lt;xsl:param name="query" select="'SELECT * FROM import1'"/&gt;
   
    &lt;xsl:template match="/"&gt;
      &lt;!-- 1. Make the connection --&gt;
      &lt;xsl:variable name="products"
                    select="sql:new('org.enhydra.instantdb.jdbc.idbDriver',
                                  'jdbc:idb:D:\instantdb\Examples\sample.prp')"/&gt;
      &lt;HTML&gt;
        &lt;HEAD&gt;
        &lt;/HEAD&gt;
        &lt;BODY&gt;
          &lt;TABLE border="1"&gt;
          &lt;!--2. Execute the query --&gt;
          &lt;xsl:variable name="table" select='sql:query($products, $query)'/&gt;
            &lt;TR&gt;
            &lt;!-- Get column-label attribute from each column-header--&gt;
            &lt;xsl:for-each select="$table/row-set/column-header"&gt;
              &lt;TH&gt;&lt;xsl:value-of select="@column-label"/&gt;&lt;/TH&gt;
            &lt;/xsl:for-each&gt;
            &lt;/TR&gt;
            &lt;xsl:apply-templates select="$table/row-set/row"/&gt;
            &lt;xsl:text&gt;&amp;#10;&lt;/xsl:text&gt;
          &lt;/TABLE&gt;
        &lt;/BODY&gt;
      &lt;/HTML&gt; 
      &lt;!-- 3. Close the connection --&gt;
      &lt;xsl:value-of select="sql:close($products)"/&gt;
    &lt;/xsl:template&gt;
  
    &lt;xsl:template match="row"&gt;
          &lt;TR&gt;
            &lt;xsl:apply-templates select="col"/&gt;
          &lt;/TR&gt;
    &lt;/xsl:template&gt;
  
    &lt;xsl:template match="col"&gt;
      &lt;TD&gt;
        &lt;!-- Here is the column data -->
        &lt;xsl:value-of select="text()"/>
      &lt;/TD>
    &lt;/xsl:template>
  
  &lt;/xsl:stylesheet&gt;
  </pre>    
      <dl>
        <dt><b>Version: </b></dt><dd>Alpha, 2.0.0, September 23, 2000</dd>
        <dt><b>Author: </b></dt><dd><a href="mailto:scott_boag@lotus.com">Scott Boag</a></dd>
      </dl>
   </body>
  </html>