com.ibm.etools.sqltoxml
Class SQLToXML

java.lang.Object
  |
  +--com.ibm.etools.sqltoxml.SQLToXML

public class SQLToXML
extends java.lang.Object

This class provides methods used by applications (such as the SQL to XML wizard) to perform database queries. The query result is obtained in an XML format. Optionally, corresponding DTD, XML schema, and XSL files of the result can be generated.


Constructor Summary
SQLToXML(QueryProperties qProperties)
          This is the only constructor.
 
Method Summary
 void execute()
          Executes a query based on information from QueryProperties given as the constructor argument.
 void execute(java.io.PrintWriter xml, java.lang.String dtdfile, java.lang.String xsdfile, java.io.PrintWriter xsl)
          Deprecated. Executes a query based on information from QueryProperties and the results are written to the PrintWriters and/or files. When any argument other than 'xml' is null, no result is generated for that particular argument. Also, if both dtdfile and xsdfile are specified, only xsdfile is generated.
 void execute(java.lang.String params, java.io.PrintWriter xml, java.lang.String dtdfile, java.lang.String xsdfile, java.io.PrintWriter xsl)
          Deprecated. Executes a query based on information from QueryProperties and the results are written to the PrintWriters and/or files. When any argument other than 'xml' is null, no result is generated for that particular argument. Also, if both dtdfile and xsdfile are specified, only xsdfile is generated. This method is used when the query contains a where-clause and its constraints are given in 'params' String argument. These constraint parameters are delimited using comma (,) in the argument.
 void execute(java.lang.String xmlfile, java.lang.String dtdfile, java.lang.String xsdfile, java.lang.String xslfile)
          Deprecated. Executes a query based on information from QueryProperties and the results are written to the files. When any argument other than 'xml' is null, no result is generated for that particular argument. Also, if both dtdfile and xsdfile are specified, only xsdfile is generated.
 void finalize()
          Closes the connection if it was created by SQLToXML.
 java.sql.Connection getConnection()
          Returns a database connection.
 org.w3c.dom.Document getCurrentDocument()
          Returns the XML document that is a result of the most recent call to the execute() method.
 org.w3c.dom.Document[] getCurrentDocuments()
          Returns the XML documents array that is a result of the most recent call to the execute() method.
 java.lang.String getDTDFile()
          Returns current DTD file name to be generated.
 java.lang.String getNextAllQuery()
          Returns a valid query string.
 java.util.Vector getNextQueries()
          Returns a sequence of valid query strings.
 java.lang.String getParameters()
          Returns the parameter values for the where-clause.
 java.lang.String getXMLFile()
          Returns current XML file name to be generated.
 java.io.PrintWriter getXMLWriter()
          Returns current PrintWriter for the XML output.
 java.lang.String getXSDFile()
          Returns current XML schema file name to be generated.
 java.lang.String getXSLFile()
          Returns current XSL file name to be generated.
 java.io.PrintWriter getXSLWriter()
          Returns current PrintWriter for the XSL output.
 void setConnection(java.sql.Connection jdbcConnection)
          Provides a JDBC connection to be used for generating the XML files.
 void setDTDFile(java.lang.String filename)
          Sets the DTD file name to be generated.
 void setGenDocType(boolean value)
          Deprecated. Controls whether or not to generate a DTD or an XML schema file for validation purposes.
 void setIndenting(boolean flag)
          Sets indentation on and off.
 void setMaxRows(int max)
          Sets the limit for the maximum number of rows to be retrieved in the generated XML.
 void setParameters(java.lang.String parameters)
          Sets the parameter values for the where-clause.
 void setQueryProperties(QueryProperties qProperties)
          Overrides current QueryProperties.
 void setTargetNamespace(java.lang.String targetNamespace)
          Sets the target namespace of the generated XML.
 void setXMLFile(java.lang.String filename)
          Sets the XML file name to be generated.
 void setXMLWriter(java.io.PrintWriter writer)
          Sets the PrintWriter to which the generated XML is directed.
 void setXSDFile(java.lang.String filename)
          Sets the XML schema file name to be generated.
 void setXSLFile(java.lang.String filename)
          Sets the XSL file name to be generated.
 void setXSLWriter(java.io.PrintWriter writer)
          Sets the PrintWriter to which the generated XSL is directed.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SQLToXML

public SQLToXML(QueryProperties qProperties)
This is the only constructor.
Method Detail

execute

public void execute()
             throws java.lang.Exception
Executes a query based on information from QueryProperties given as the constructor argument. The artifacts that can be generated include XML, XML schema, DTD, and XSL files. To generate artifacts other than XML, the file names or PrintWriters need to be provided by using relevant set accessors before using this method. Additionally the XML output can be obtained as a DOM document through the getCurrentDocument() or getCurrentDocuments() method call.
 Usage pattern:
 
   QueryProperties properties = new QueryProperties();
   ... set the query property values ...
   SQLToXML sqltoxml = new SQLToXML(properties);
   ... set necessary values for sqltoxml ...
   sqltoxml.execute();
   // Next line is if you want to retrieve the XML document 
   Document doc = sqltoxml.getCurrentDocument();
 
 
Throws:
java.lang.Exception - Thrown when the execution fails.
See Also:
QueryProperties, setXMLFile(java.lang.String), setXMLWriter(java.io.PrintWriter), setDTDFile(java.lang.String), setXSDFile(java.lang.String), setXSLFile(java.lang.String), setXSLWriter(java.io.PrintWriter), setParameters(java.lang.String)

setXMLFile

public void setXMLFile(java.lang.String filename)
                throws java.lang.Exception
Sets the XML file name to be generated. This method cannot be used in combination with setXMLWriter(PrintWriter).
Parameters:
filename - An XML file name to be generated
Throws:
java.lang.Exception - Thrown if setXMLWriter(PrintWriter) or setXSLWriter(PrintWriter) has been called already.
See Also:
setXMLWriter(java.io.PrintWriter)

getXMLFile

public java.lang.String getXMLFile()
Returns current XML file name to be generated.
Returns:
An XML file name.
See Also:
setXMLFile(java.lang.String)

setXMLWriter

public void setXMLWriter(java.io.PrintWriter writer)
                  throws java.lang.Exception
Sets the PrintWriter to which the generated XML is directed. This method cannot be used in combination with setXMLFile(String).
Parameters:
filename - A PrintWriter where the XML is going to be directed.
Throws:
java.lang.Exception - Thrown if setXMLFile(PrintWriter) or setXSLFile(PrintWriter) has been called already.
See Also:
setXMLFile(java.lang.String)

getXMLWriter

public java.io.PrintWriter getXMLWriter()
Returns current PrintWriter for the XML output.
Returns:
A PrintWriter for the XML output.
See Also:
setXMLWriter(java.io.PrintWriter)

setXSDFile

public void setXSDFile(java.lang.String filename)
                throws java.lang.Exception
Sets the XML schema file name to be generated. This method cannot be used in combination with setDTDFile(String).
Parameters:
filename - An XML schema file name to be generated
Throws:
java.lang.Exception - Thrown if setDTDFile(String) has been called already.
See Also:
setDTDFile(java.lang.String)

getXSDFile

public java.lang.String getXSDFile()
Returns current XML schema file name to be generated.
Returns:
An XML schema file name.
See Also:
setXSDFile(java.lang.String)

setDTDFile

public void setDTDFile(java.lang.String filename)
                throws java.lang.Exception
Sets the DTD file name to be generated. This method cannot be used in combination with setXSDFile(String).
Parameters:
filename - A DTD file name to be generated
Throws:
java.lang.Exception - Thrown if setXSDFile(String) has been called already.
See Also:
setDTDFile(java.lang.String)

getDTDFile

public java.lang.String getDTDFile()
Returns current DTD file name to be generated.
Returns:
A DTD file name.
See Also:
setDTDFile(java.lang.String)

setXSLFile

public void setXSLFile(java.lang.String filename)
                throws java.lang.Exception
Sets the XSL file name to be generated. This method cannot be used in combination with setXSLWriter(PrintWriter).
Parameters:
filename - An XSL file name to be generated
Throws:
java.lang.Exception - Thrown if setXSLWriter(PrintWriter) or setXMLWriter(PrintWriter) has been called already.
See Also:
setXSLWriter(java.io.PrintWriter)

getXSLFile

public java.lang.String getXSLFile()
Returns current XSL file name to be generated.
Returns:
An XSL file name.
See Also:
setXSLFile(java.lang.String)

setXSLWriter

public void setXSLWriter(java.io.PrintWriter writer)
                  throws java.lang.Exception
Sets the PrintWriter to which the generated XSL is directed. This method cannot be used in combination with setXSLFile(String).
Parameters:
filename - A PrintWriter where the XSL is going to be directed.
Throws:
java.lang.Exception - Thrown if setXSLFile(PrintWriter) or setXMLFile(PrintWriter) has been called already.
See Also:
setXSLFile(java.lang.String)

getXSLWriter

public java.io.PrintWriter getXSLWriter()
Returns current PrintWriter for the XSL output.
Returns:
A PrintWriter for the XSL output.
See Also:
setXSLWriter(java.io.PrintWriter)

setParameters

public void setParameters(java.lang.String parameters)
Sets the parameter values for the where-clause. This method is intended to be used when the query contains the where-clause. For example,
   select * from EMPLOYEE where EMP_NO = :empno
 
From the above example, the value to be replaced for :empno is given in the parameters argument. If there are multiple constraint values, they are delimited using comma (,) in the parameters like in the following example.
 
   String params = "87316,'Toronto'"; 
   sqltoxml.setParameters(params);
 
 
Parameters:
parameters - The where-clause parameter values when they exist

getParameters

public java.lang.String getParameters()
Returns the parameter values for the where-clause.
Returns:
The where-clause parameter values when they exist.
See Also:
setParameters(java.lang.String)

setMaxRows

public void setMaxRows(int max)
Sets the limit for the maximum number of rows to be retrieved in the generated XML. By default, there is no limit.
Parameters:
max - The limit for the number of rows. Zero means there is no limit.

setIndenting

public void setIndenting(boolean flag)
Sets indentation on and off. Indentation is on by default.
Parameters:
flag - false if indentation should be off.

getCurrentDocuments

public org.w3c.dom.Document[] getCurrentDocuments()
Returns the XML documents array that is a result of the most recent call to the execute() method. Unless the GENERATE_ID_AND_IDREF with RECURSIVE option is used, the result contains only one document.
Returns:
An array of XML documents
See Also:
getCurrentDocument()

getCurrentDocument

public org.w3c.dom.Document getCurrentDocument()
Returns the XML document that is a result of the most recent call to the execute() method. If the GENERATE_ID_AND_IDREF with RECURSIVE option was used, the main XML document is returned.
Returns:
An XML document
See Also:
getCurrentDocuments()

setConnection

public void setConnection(java.sql.Connection jdbcConnection)
Provides a JDBC connection to be used for generating the XML files. This method becomes useful when an application program wants to use its own connection management mechanism such as connection pooling. If this method is not called before any of the execute() methods, SQLToXML creates its own connection using the values from QueryProperties.
Parameters:
jdbcConnection - A JDBC connection

getConnection

public java.sql.Connection getConnection()
                                  throws java.lang.Exception
Returns a database connection. If no connection exists, this method creates a new connection using the values from QueryProperties.
Returns:
A JDBC connection used for the query
Throws:
java.lang.Exception - Thrown when a connection is not available.

finalize

public void finalize()
Closes the connection if it was created by SQLToXML. If the connection was supplied externally (by using setConnection()), the connection is not closed. This method is called by the JVM when SQLToXML is garbage-collected.

setGenDocType

public void setGenDocType(boolean value)
Deprecated. Controls whether or not to generate a DTD or an XML schema file for validation purposes.

Parameters:
value - false for not generating a DTD or an XML schema file, and true otherwise.

setQueryProperties

public void setQueryProperties(QueryProperties qProperties)
Overrides current QueryProperties.

execute

public void execute(java.io.PrintWriter xml,
                    java.lang.String dtdfile,
                    java.lang.String xsdfile,
                    java.io.PrintWriter xsl)
             throws java.lang.Exception
Deprecated. Executes a query based on information from QueryProperties and the results are written to the PrintWriters and/or files. When any argument other than 'xml' is null, no result is generated for that particular argument. Also, if both dtdfile and xsdfile are specified, only xsdfile is generated.

Parameters:
xml - A PrintWriter for an XML result.
dtdfile - A DTD file name for the xml.
xsdfile - An XML schema file name for the xml.
xsl - A PrintWriter for a default XSL.
Throws:
java.lang.Exception - Thrown when the execution fails.
See Also:
QueryProperties

execute

public void execute(java.lang.String params,
                    java.io.PrintWriter xml,
                    java.lang.String dtdfile,
                    java.lang.String xsdfile,
                    java.io.PrintWriter xsl)
             throws java.lang.Exception
Deprecated. Executes a query based on information from QueryProperties and the results are written to the PrintWriters and/or files. When any argument other than 'xml' is null, no result is generated for that particular argument. Also, if both dtdfile and xsdfile are specified, only xsdfile is generated. This method is used when the query contains a where-clause and its constraints are given in 'params' String argument. These constraint parameters are delimited using comma (,) in the argument.

Parameters:
params - where-clause constraint parameters delimited by comma(',').
xml - A PrintWriter for an XML result.
dtdfile - A DTD file name for the xml.
xsdfile - An XML schema file name for the xml.
xsl - A PrintWriter for a default XSL.
Throws:
java.lang.Exception - Thrown when the execution fails.
See Also:
QueryProperties

execute

public void execute(java.lang.String xmlfile,
                    java.lang.String dtdfile,
                    java.lang.String xsdfile,
                    java.lang.String xslfile)
             throws java.lang.Exception
Deprecated. Executes a query based on information from QueryProperties and the results are written to the files. When any argument other than 'xml' is null, no result is generated for that particular argument. Also, if both dtdfile and xsdfile are specified, only xsdfile is generated.

Parameters:
xmlfile - An XML file name for the query result.
dtdfile - A DTD file name for the xmlfile.
xsdfile - An XML schema file name for the xmlfile.
xslfile - An XSL file name for a default XSL.
Throws:
java.lang.Exception - Thrown when the execution fails.
See Also:
QueryProperties

getNextAllQuery

public java.lang.String getNextAllQuery()
Returns a valid query string. This method returns a valid query string only when
   1) Format option is ID_AND_IDREF, and
   2) Recurse option is 'TRUE'
 
For example, when a column from the current query is a foreign key to a primary key column of table A, this will return a string 'select * from A'. Refer to the sample servlet XMLIntegratorServlet.java for a typical use of this method.
Returns:
A select statement for a table referenced by a foreign key

getNextQueries

public java.util.Vector getNextQueries()
Returns a sequence of valid query strings. This method returns a Vector of valid query strings only when
   1) Format option is ID_AND_IDREF, and
   2) Recurse option is 'TRUE'
 
For example, when a column from the current query is a foreign key to a primary key column ID (with value 123) of table A, this will return a string 'select * from A where ID = 123'. Refer to the sample servlet XMLIntegratorServlet.java for a typical use of this method.
Returns:
A select statement (with the where-clause) for a table row referenced by a foreign key

setTargetNamespace

public void setTargetNamespace(java.lang.String targetNamespace)
Sets the target namespace of the generated XML. A target namespace is automatically used in the output XML only when XML is generated including an XML schema. This method can be used to add the target namespace to the XML for other cases when an XML schema is not generated.
Parameters:
targetNamespace - The target namespace name of the output XML