com.evanmclean.evlib.sql
Class RsXml

java.lang.Object
  extended by com.evanmclean.evlib.sql.RsXml

public class RsXml
extends Object

Converts a result set to XML output. In it's simplest form it writes one output record for each input record. It can also output sub-records to any level, based on break values of columns that can change for each row.

Author:
Evan McLean McLean Computer Services (see the overview for copyright and licensing.)

Field Summary
static String DEFAULT_DATE_FORMAT
          The default format used ("yyyy-MM-dd") to convert a date column to a string.
static String DEFAULT_ENCODING
          The default encoding ("ISO-8859-1") which will be written to the XML declaration.
static String DEFAULT_TIME_FORMAT
          The default format used ("HH:mm:ss.SSS") to convert a time column to a string.
static String DEFAULT_TIMESTAMP_FORMAT
          The default format used ("yyyy-MM-dd HH:mm:ss.SSS") to convert a timestamp column to a string.
 
Constructor Summary
RsXml()
          Default constructor.
RsXml(ResultSet rs)
          Sets the record set to be used.
RsXml(ResultSet rs, String record_name)
          Sets the record set and single record name to be used, thus writing one record per row returned in the result set, and including all columns.
RsXml(ResultSet rs, String container_element_name, String record_name)
          Sets the record set, container name and single record name to be used, thus writing one record per row returned in the result set, and including all columns.
RsXml(ResultSet rs, String record_name, String[] columns)
          Sets the record set and single record name to be used, thus writing one record per row returned in the result set, and including only the specified columns.
RsXml(ResultSet rs, String container_element_name, String record_name, String[] columns)
          Sets the record set, container name and single record name to be used, thus writing one record per row returned in the result set, only including the specified columns.
 
Method Summary
 void clearCdataColumns()
          Clear the list of the columns to be wrapped in a <![CDATA[ container instead of the usual XML encoding.
 void clearColumnAliases()
          Clear all the column aliases.
 void clearContainerElementName()
          No container element (and hence, no XML declaration) will be written on a call to write.
 void clearEncoding()
          No encoding attribute will be written in the XML declaration.
protected  void closingLevel(Writer out, int lvl, String record_name)
          Called just before closing the level, allowing any specialised action to take place.
 boolean eors()
          Indicates if we have reached the end of the record set.
 String[][] getBreakColumns()
          The break columns being used.
 String[] getCdataColumns()
          A list of the columns to be wrapped in a <![CDATA[ container instead of the usual XML encoding.
 String[][] getColumnAliases()
          By default, the column name is used as the element name, however aliases can be used.
 String[][] getColumns()
          The columns to be written at each level.
 String getContainerAttributes()
          A snippet of XML attributes that will be written at part of the container element (default none).
 String getContainerElementElementName()
          The name of the container element that will be written surrounding all the records in the next write.
protected  String getDate(Object obj, String column, int sql_type)
          Converts a date to a string.
 DateFormat getDateFormat()
          For formatting object used to convert date columns to strings.
protected  String getDouble(Object obj, String column, int sql_type)
          Converts a float or double to a string, trimming any trailing zeros and decimal point.
 String getEncoding()
          The value of the encoding attribute that will be written in the XML declaration (e.g.
 String getLineSeperator()
          The line separator to be used after the XML declaration, and for pretty printing (default is system property).
 String getNullSnippet()
          If the column is null, then then this XML snipped is included in the element being written (default blank).
 Object getObject(String name)
          Return the specified object from the last row read.
 Object[] getObjects()
          Return the objects from the last row read.
 String[] getRecordNames()
          The record names being used.
 ResultSet getResultSet()
          Gets the result set to be read, or null if it has not been set yet.
protected  String getTime(Object obj, String column, int sql_type)
          Converts a time to a string, removing any trailing zeros or decimal point.
 DateFormat getTimeFormat()
          For formatting object used to convert time columns to strings.
protected  String getTimestamp(Object obj, String column, int sql_type)
          Converts a timestamp to a string, removing any trailing zeros or decimal point.
 DateFormat getTimestampFormat()
          For formatting object used to convert timestamp columns to strings.
protected  String getValue(Object obj, String column, int sql_type)
          Converts the object retrieved from the result set to a string.
 boolean isEmptyAsOpenAndCloseElement()
          By default, elements with an empty (or null) value will be written as a single element (e.g.
 boolean isIncludeXmlDeclaration()
          Indicates if the XML declaration (i.e.
 boolean isLowercase()
          Indicates if all column names (not including aliased columns) are forced to lowercase before being written as element names (default true).
 boolean isPrettyIndent()
          Indicates if the XML is written with newlines and indentation (default true when pretty print is true, false otherwise).
 boolean isPrettyPrint()
          Indicates if the XML is written with newlines and (possibly) indentation (default false).
protected  void openingLevel(Writer out, int lvl, String record_name)
          Called just after opening the level, allowing any specialised action to take place.
 int read()
          The number of individual rows read from the record set in the last write operation.
 void setCdataColumns(String[] colmns)
          A list of the columns to be wrapped in a <![CDATA[ container instead of the usual XML encoding.
 void setColumnAliases(Map<? extends String,? extends String> column_aliases)
          By default, the column name is used as the element name, however aliases can be used.
 void setColumnAliases(String[][] column_aliases)
          By default, the column name is used as the element name, however aliases can be used.
 void setContainerAttributes(String container_attributes)
          A snippet of XML attributes that will be written at part of the container element (default none).
 void setContainerElementName(String container_element_name)
          The name of the container element that will be written surrounding all the records in the next write.
 void setDateFormat(DateFormat date_format)
          For formatting object used to convert date columns to strings.
 void setEmptyAsOpenAndCloseElement(boolean empty_as_open_and_close_element)
          By default, elements with an empty (or null) value will be written as a single element (e.g.
 void setEncoding(String enc)
          The value of the encoding attribute that will be written in the XML declaration (e.g.
 void setIncludeXmlDeclaration(boolean include_xml_declaration)
          Indicates if the XML declaration (i.e.
 void setLineSeperator(String line_separator)
          The line separator to be used after the XML declaration, and for pretty printing (default is system property).
 void setLowercase(boolean lwrcase)
          Set if all column names (not including aliased columns) are forced to lowercase before being written as element names (default true).
 void setNullSnippet(String null_snippet)
          If the column is null, then then this XML snipped is included in the element being written (default blank).
protected  Object setObject(String name, Object newobj)
          Set the object for the specified column.
 void setPretty(boolean pretty_print, boolean pretty_indent)
          Indicates if the XML is written with newlines and indentation (default false).
 void setPrettyPrint(boolean pretty_print)
          Indicates if the XML is written with newlines and indentation (default false).
 void setRecord(String record_name)
          Sets the record name to be used, thus writing one record per row returned in the result set, and including all columns.
 void setRecord(String record_name, String[] columns_filter)
          Sets the single record name to be used, thus writing one record per row returned in the result set, and including only the specified columns.
 void setRecords(String[] record_names, String[][] break_columns, String[][] columns_filter)
          Sets the details of the XML records to be written, with sub-records possible.
 void setResultSet(ResultSet new_rs)
          Sets the result set to be read for producing the XML.
 void setTimeFormat(DateFormat time_format)
          For formatting object used to convert time columns to strings.
 void setTimestampFormat(DateFormat timestamp_format)
          For formatting object used to convert timestamp columns to strings.
 int totalRead()
          The total number of individual rows read from the record set across all write operations.
 int totalWritten()
          The total number of top level records written in across all write operations.
protected  String trimTrailingZeros(String str)
          Utility function that, if the string contains a decimal point, trims trailing zeros (up to and including the decimal point) off the end of the string.
 void write(Writer out)
          Write all remaining records from the result set as XML to the specified writer.
 boolean write(Writer out, int limit)
          Write records from the result set as XML to the specified writer.
protected  void writeElement(Writer out, String element_name, String value, boolean cdata)
           
 int written()
          The number of top level records written in the last write operation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING
The default encoding ("ISO-8859-1") which will be written to the XML declaration.

See Also:
Constant Field Values

DEFAULT_DATE_FORMAT

public static final String DEFAULT_DATE_FORMAT
The default format used ("yyyy-MM-dd") to convert a date column to a string.

See Also:
Constant Field Values

DEFAULT_TIME_FORMAT

public static final String DEFAULT_TIME_FORMAT
The default format used ("HH:mm:ss.SSS") to convert a time column to a string.

See Also:
Constant Field Values

DEFAULT_TIMESTAMP_FORMAT

public static final String DEFAULT_TIMESTAMP_FORMAT
The default format used ("yyyy-MM-dd HH:mm:ss.SSS") to convert a timestamp column to a string.

See Also:
Constant Field Values
Constructor Detail

RsXml

public RsXml()
Default constructor. A result set and at least one record name must be specified before you can write.


RsXml

public RsXml(ResultSet rs)
Sets the record set to be used. At least one record name must be specified before you can write.

Parameters:
rs - Result set to use.

RsXml

public RsXml(ResultSet rs,
             String record_name)
Sets the record set and single record name to be used, thus writing one record per row returned in the result set, and including all columns. By default no XML declaration or container element will be written.

Parameters:
rs - Result set to use.
record_name - The single record name to be used.

RsXml

public RsXml(ResultSet rs,
             String container_element_name,
             String record_name)
Sets the record set, container name and single record name to be used, thus writing one record per row returned in the result set, and including all columns. By default an XML declaration with the default encoding and the container element will be written.

Parameters:
rs - Result set to use.
container_element_name - The name of container element to be written, surrounding all the records written.
record_name - The single record name to be used.

RsXml

public RsXml(ResultSet rs,
             String container_element_name,
             String record_name,
             String[] columns)
Sets the record set, container name and single record name to be used, thus writing one record per row returned in the result set, only including the specified columns. By default an XML declaration with the default encoding and the container element will be written.

Parameters:
rs - Result set to use.
container_element_name - The name of container element to be written, surrounding all the records written.
record_name - The single record name to be used.
columns - The only columns that will be written in the XML output.

RsXml

public RsXml(ResultSet rs,
             String record_name,
             String[] columns)
Sets the record set and single record name to be used, thus writing one record per row returned in the result set, and including only the specified columns. By default no XML declaration or container element will be written.

Parameters:
rs - Result set to use.
record_name - The single record name to be used.
columns - The only columns that will be written in the XML output.
Method Detail

clearCdataColumns

public void clearCdataColumns()
Clear the list of the columns to be wrapped in a <![CDATA[ container instead of the usual XML encoding.


clearColumnAliases

public void clearColumnAliases()
Clear all the column aliases.


clearContainerElementName

public void clearContainerElementName()
No container element (and hence, no XML declaration) will be written on a call to write.


clearEncoding

public void clearEncoding()
No encoding attribute will be written in the XML declaration.


eors

public boolean eors()
             throws SQLException
Indicates if we have reached the end of the record set.

Returns:
True if we have reached the end of the record set.
Throws:
SQLException

getBreakColumns

public String[][] getBreakColumns()
The break columns being used.

Returns:
The break columns being used, or an empty array if none have been specified yet.

getCdataColumns

public String[] getCdataColumns()
A list of the columns to be wrapped in a <![CDATA[ container instead of the usual XML encoding.

Returns:
The columns.

getColumnAliases

public String[][] getColumnAliases()
By default, the column name is used as the element name, however aliases can be used.

Returns:
Return the array map of column names and alias values that will be used.

getColumns

public String[][] getColumns()
The columns to be written at each level.

Returns:
The columns to be written at each level, or an empty array if none have been specified yet.

getContainerAttributes

public String getContainerAttributes()
A snippet of XML attributes that will be written at part of the container element (default none). This snippet must be valid XML. For example: xmlns:h="http://www.w3.org/TR/html4/"

Returns:
The container snippet.

getContainerElementElementName

public String getContainerElementElementName()
The name of the container element that will be written surrounding all the records in the next write. By default this is an empty string, indicating no container (and hence, no XML declaration) will be written.

Returns:
The name of the container element.

getDateFormat

public DateFormat getDateFormat()
For formatting object used to convert date columns to strings.

Returns:
The date formatting object.

getEncoding

public String getEncoding()
The value of the encoding attribute that will be written in the XML declaration (e.g. " <?xml version="1.0" encoding="ISO-8859-1"?> "). By default the value is specified by the DEFAULT_ENCODING field. If this is an empty string then no encoding attribute will be written.

Returns:
The encoding attribute value.

getLineSeperator

public String getLineSeperator()
The line separator to be used after the XML declaration, and for pretty printing (default is system property).

Returns:
The line separator.

getNullSnippet

public String getNullSnippet()
If the column is null, then then this XML snipped is included in the element being written (default blank). For example, if this property is set to "null="true"" then the element will be written as "<element null="true" /> ".

Returns:
The snippet used for nulls.

getObject

public Object getObject(String name)
Return the specified object from the last row read.

Parameters:
name - The column name.
Returns:
The specified object.

getObjects

public Object[] getObjects()
Return the objects from the last row read.

Returns:
The objects.

getRecordNames

public String[] getRecordNames()
The record names being used.

Returns:
The record names being used, or an empty array if none have been specified yet.

getResultSet

public ResultSet getResultSet()
Gets the result set to be read, or null if it has not been set yet.

Returns:
Gets the result set to be read, or null if it has not been set yet.

getTimeFormat

public DateFormat getTimeFormat()
For formatting object used to convert time columns to strings.

Returns:
The formatting object.

getTimestampFormat

public DateFormat getTimestampFormat()
For formatting object used to convert timestamp columns to strings.

Returns:
The formatting object.

isEmptyAsOpenAndCloseElement

public boolean isEmptyAsOpenAndCloseElement()
By default, elements with an empty (or null) value will be written as a single element (e.g. "<element /gt;"). If this is true then it will be written as an open element followed by a close element (e.g. "<element></element>").

Returns:
True if we write as a separate open and close element.

isIncludeXmlDeclaration

public boolean isIncludeXmlDeclaration()
Indicates if the XML declaration (i.e. " <?xml version="1.0"?>" will be written at the start of the write (default true). Note: The XML declaration will not be written if a container name has not been specified regardless of the value of this flag.

Returns:
Will write the XML declaration.

isLowercase

public boolean isLowercase()
Indicates if all column names (not including aliased columns) are forced to lowercase before being written as element names (default true).

Returns:
True if element names are always lowercase.

isPrettyIndent

public boolean isPrettyIndent()
Indicates if the XML is written with newlines and indentation (default true when pretty print is true, false otherwise).

Returns:
True if pretty printing with indentation.

isPrettyPrint

public boolean isPrettyPrint()
Indicates if the XML is written with newlines and (possibly) indentation (default false).

Returns:
True if pretty printing.

read

public int read()
The number of individual rows read from the record set in the last write operation.

Returns:
int

setCdataColumns

public void setCdataColumns(String[] colmns)
A list of the columns to be wrapped in a <![CDATA[ container instead of the usual XML encoding.

Parameters:
colmns - The list of columns.

setColumnAliases

public void setColumnAliases(Map<? extends String,? extends String> column_aliases)
By default, the column name is used as the element name, however aliases can be used.

Parameters:
column_aliases - The column names and aliases to be used.

setColumnAliases

public void setColumnAliases(String[][] column_aliases)
By default, the column name is used as the element name, however aliases can be used.

Parameters:
column_aliases - The column names and aliases to be used.

setContainerAttributes

public void setContainerAttributes(String container_attributes)
A snippet of XML attributes that will be written at part of the container element (default none). This snippet must be valid XML. For example: xmlns:h="http://www.w3.org/TR/html4/"

Parameters:
container_attributes - A snippet of XML attributes to be included, or a blank/null string to indicae no attributes.

setContainerElementName

public void setContainerElementName(String container_element_name)
The name of the container element that will be written surrounding all the records in the next write. By default this is an empty string, indicating no container (and hence, no XML declaration) will be written.

Parameters:
container_element_name - The name of the container element, or blank/null to indicate no container element is to be written.

setDateFormat

public void setDateFormat(DateFormat date_format)
For formatting object used to convert date columns to strings.

Parameters:
date_format -

setEmptyAsOpenAndCloseElement

public void setEmptyAsOpenAndCloseElement(boolean empty_as_open_and_close_element)
By default, elements with an empty (or null) value will be written as a single element (e.g. "<element /gt;"). If this is true then it will be written as an open element followed by a close element (e.g. "<element></element>").

Parameters:
empty_as_open_and_close_element -

setEncoding

public void setEncoding(String enc)
The value of the encoding attribute that will be written in the XML declaration (e.g. " <?xml version="1.0" encoding="ISO-8859-1"?> "). By default the value is specified by the DEFAULT_ENCODING field. If this is a blank string or null then no encoding attribute will be written.

Parameters:
enc - The value of the encoding attribute, or a blank/null string to indicate no encoding attribute is to be written.

setIncludeXmlDeclaration

public void setIncludeXmlDeclaration(boolean include_xml_declaration)
Indicates if the XML declaration (i.e. " <?xml version="1.0"?>") will be written at the start of the write (default true). Note: The XML declaration will not be written if a container name has not been specified regardless of the value of this flag.

Parameters:
include_xml_declaration -

setLineSeperator

public void setLineSeperator(String line_separator)
The line separator to be used after the XML declaration, and for pretty printing (default is system property).

Parameters:
line_separator - The line separator string to use. If empty or null then the system default will be used.

setLowercase

public void setLowercase(boolean lwrcase)
Set if all column names (not including aliased columns) are forced to lowercase before being written as element names (default true).

Parameters:
lwrcase - True if all column names are forced to lowercase before being written.

setNullSnippet

public void setNullSnippet(String null_snippet)
If the column is null, then then this XML snipped is included in the element being written (default blank). For example, if this property is set to "null="true"" then the element will be written as "<element null="true" /> ".

Parameters:
null_snippet -

setPretty

public void setPretty(boolean pretty_print,
                      boolean pretty_indent)
Indicates if the XML is written with newlines and indentation (default false).

Parameters:
pretty_print -
pretty_indent -

setPrettyPrint

public void setPrettyPrint(boolean pretty_print)
Indicates if the XML is written with newlines and indentation (default false).

Parameters:
pretty_print -

setRecord

public void setRecord(String record_name)
Sets the record name to be used, thus writing one record per row returned in the result set, and including all columns.

Parameters:
record_name - The single record name to be used.

setRecord

public void setRecord(String record_name,
                      String[] columns_filter)
Sets the single record name to be used, thus writing one record per row returned in the result set, and including only the specified columns.

Parameters:
record_name - The single record name to be used.
columns_filter - The only columns that will be written in the XML output.

setRecords

public void setRecords(String[] record_names,
                       String[][] break_columns,
                       String[][] columns_filter)
Sets the details of the XML records to be written, with sub-records possible.

Parameters:
record_names - The record element names to be used for each level.
break_columns - The columns used at each level to indicate when a new sub record is to be written. The length of this array is one less than then record_names.
columns_filter - The columns to be written at each record level. It's length is usually equal to the length of the record names array, however if it is one less, then all the columns that have not been specified so far are written in the lowest level record.

setResultSet

public void setResultSet(ResultSet new_rs)
Sets the result set to be read for producing the XML.

Parameters:
new_rs - The result set to be read to product the XML. May not be null.

setTimeFormat

public void setTimeFormat(DateFormat time_format)
For formatting object used to convert time columns to strings.

Parameters:
time_format -

setTimestampFormat

public void setTimestampFormat(DateFormat timestamp_format)
For formatting object used to convert timestamp columns to strings.

Parameters:
timestamp_format -

totalRead

public int totalRead()
The total number of individual rows read from the record set across all write operations.

Returns:
Total rows read.

totalWritten

public int totalWritten()
The total number of top level records written in across all write operations. If there is only one record level being used, this will be the same as the totalRead() value.

Returns:
Total top level records written.

write

public void write(Writer out)
           throws IOException,
                  SQLException
Write all remaining records from the result set as XML to the specified writer. If all rows have already been written, and the container element name has been specified then an empty XML document will be written. Use eors() to avoid this.

Parameters:
out - The writer to write the XML to.
Throws:
IOException
SQLException

write

public boolean write(Writer out,
                     int limit)
              throws IOException,
                     SQLException
Write records from the result set as XML to the specified writer. If all rows have already been written, and the container element name has been specified then an empty XML document will be written. Use eors() to avoid this.

Parameters:
out - The writer to write the XML to.
limit - The maximum number of (top-level) records to write (or 0 for all remaining records).
Returns:
True if there are still more records to be written.
Throws:
IOException
SQLException

written

public int written()
The number of top level records written in the last write operation. If there is only one record level being used, this will be the same as the read() value.

Returns:
Number of top level records written in the last write operation.

closingLevel

protected void closingLevel(Writer out,
                            int lvl,
                            String record_name)
                     throws IOException
Called just before closing the level, allowing any specialised action to take place. By default it does nothing.

Parameters:
out - The writer we are sending our XML to.
lvl - The level that is being closed.
record_name - The record that is being closed.
Throws:
IOException - Can be thrown if there is an issue.

getDate

protected String getDate(Object obj,
                         String column,
                         int sql_type)
Converts a date to a string.

Parameters:
obj -
column -
sql_type -
Returns:
Date formatted as a string.

getDouble

protected String getDouble(Object obj,
                           String column,
                           int sql_type)
Converts a float or double to a string, trimming any trailing zeros and decimal point.

Parameters:
obj -
column -
sql_type -
Returns:
Double formatted as a string.

getTime

protected String getTime(Object obj,
                         String column,
                         int sql_type)
Converts a time to a string, removing any trailing zeros or decimal point.

Parameters:
obj -
column -
sql_type -
Returns:
Time formatted as a string.

getTimestamp

protected String getTimestamp(Object obj,
                              String column,
                              int sql_type)
Converts a timestamp to a string, removing any trailing zeros or decimal point.

Parameters:
obj -
column -
sql_type -
Returns:
Tiemstamp formatted as a string.

getValue

protected String getValue(Object obj,
                          String column,
                          int sql_type)
Converts the object retrieved from the result set to a string. By default dispatches a float or double to getDouble, a date or time related object to the appropriate method, otherwise just calls toString on the object passed in.

Parameters:
obj - The object from the result set.
column - The name of the column.
sql_type - The SQL type of the column, a constant from java.sql.Types.
Returns:
The object converted to a string.

openingLevel

protected void openingLevel(Writer out,
                            int lvl,
                            String record_name)
Called just after opening the level, allowing any specialised action to take place. By default it does nothing.

Parameters:
out - The writer we are sending our XML to.
lvl - The level that is being closed.
record_name - The record that is being closed.

setObject

protected Object setObject(String name,
                           Object newobj)
Set the object for the specified column.

Parameters:
name - The column name.
newobj - The new object to put in it's place.
Returns:
The original object for this column.

trimTrailingZeros

protected String trimTrailingZeros(String str)
Utility function that, if the string contains a decimal point, trims trailing zeros (up to and including the decimal point) off the end of the string.

Parameters:
str -
Returns:
The string with trailing zeros and decimal point trimmed off.

writeElement

protected void writeElement(Writer out,
                            String element_name,
                            String value,
                            boolean cdata)
                     throws IOException
Throws:
IOException