XmlVTI (Apache Derby V10.14 Internals)

java.lang.Object
- org.apache.derby.vti.VTITemplate
- - org.apache.derby.vti.StringColumnVTI
  - - org.apache.derby.vti.XmlVTI

All Implemented Interfaces:: java.lang.AutoCloseable, java.sql.ResultSet, java.sql.Wrapper, AwareVTI

public class XmlVTI
extends StringColumnVTI

This is a VTI designed to read XML files which are structured like row sets.

XML files parsed by this VTI are always processed with external entity expansion disabled and secure parser processing enabled.

There are two invocation formats provided by this VTI.

One form of this VTI takes the following arguments. This form is useful when all of the columns in the row can be constructed from data nested INSIDE the row Element.

xmlResourceName - The name of an xml file.
rowTag - The tag of the element which contains the row-structured content.
childTags - The attributes and descendant elements inside the row element which should be treated as columns.

Here is a sample declaration of this first form of the XmlVTI:

 create function findbugs( xmlResourceName varchar( 32672 ), rowTag varchar( 32672 ), childTags varchar( 32672 )... )
 returns table
 (
      className   varchar( 32672 ),
      bugCount    int
 )
 language java parameter style derby_jdbc_result_set no sql
 external name 'org.apache.derby.vti.XmlVTI.xmlVTI';

...and here is a sample invocation:

 create view findbugs as
 select *
 from table
 (
      findbugs
      (
          'findbugs.xml',
          'ClassStats',
          'class', 'bugs'
      )
  ) v;
 
 select * from findbugs where bugCount != 0;

A second form of this VTI takes the following arguments. This form is useful when some of the columns in the row are "inherited" from outer elements inside which the row element nests:

xmlResourceName - The name of an xml file.
rowTag - The tag of the element which contains the row-structured content.
parentTags - Attributes and elements (to be treated as columns) from outer elements in which the rowTag is nested.
childTags - Attributes and elements (to be treated as columns) inside the row element.

Here is a sample declaration of this second form of the XmlVTI. Using the second form involves declaring an ArrayList type and a factory method too:

 create type ArrayList external name 'java.util.ArrayList' language java;
 
 create function asList( cell varchar( 32672 ) ... ) returns ArrayList
 language java parameter style derby no sql
 external name 'org.apache.derby.vti.XmlVTI.asList';
 
 create function optTrace
 (
     xmlResourceName varchar( 32672 ),
     rowTag varchar( 32672 ),
     parentTags ArrayList,
     childTags ArrayList
 )
 returns table
 (
     stmtID    int,
     queryID   int,
     complete  boolean,
     summary   varchar( 32672 ),
     type        varchar( 50 ),
     estimatedCost        double,
     estimatedRowCount    int
 )
 language java parameter style derby_jdbc_result_set no sql
 external name 'org.apache.derby.vti.XmlVTI.xmlVTI';
 
 create view optTrace as
        select *
        from table
        (
             optTrace
             (
                 '/Users/me/derby/mainline/z.xml',
                 'planCost',
                 asList( 'stmtID', 'queryID', 'complete' ),
                 asList( 'summary', 'type', 'estimatedCost', 'estimatedRowCount' )
             )
         ) v
 ;
 
 select * from optTrace
 where stmtID = 6 and complete
 order by estimatedCost;

Nested Class Summary

Nested Classes
Modifier and Type Class Description

private class XmlVTI.XMLErrorHandler
- Nested classes/interfaces inherited from class org.apache.derby.vti.VTITemplate
  VTITemplate.ColumnDescriptor

Nested Classes
Modifier and Type	Class	Description
`private class`	`XmlVTI.XMLErrorHandler`

Field Summary

Fields
Modifier and Type	Field	Description
`private javax.xml.parsers.DocumentBuilder`	`_builder`
`private java.lang.String[]`	`_currentRow`
`private int`	`_firstChildTagIdx`
`private org.w3c.dom.NodeList`	`_rawRows`
`private int`	`_rowCount`
`private int`	`_rowIdx`
`private java.lang.String`	`_rowTag`
`private java.io.InputStream`	`_xmlResource`

Fields inherited from interface java.sql.ResultSet
CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE

Constructor Summary

Constructors
Constructor	Description
`XmlVTI(java.io.InputStream xmlResource, java.lang.String rowTag, int firstChildTagIdx, java.lang.String... columnTags)`	Build an XmlVTI.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`static java.util.ArrayList<java.lang.String>`	`asList(java.lang.String... cells)`	Factory method to create an ArrayList
`void`	`close()`
`private java.lang.String`	`findColumnValue(org.w3c.dom.Element rawRow, int columnNumber)`	Find the value of a column inside an element.
`java.sql.ResultSetMetaData`	`getMetaData()`
`protected java.lang.String`	`getRawColumn(int columnNumber)`	Get the string value of the column in the current row identified by the 1-based columnNumber.
`boolean`	`next()`
`private void`	`parseRow(int rowNumber)`	Parse a row into columns.
`private void`	`readRows()`	Fault in the list of rows.
`private java.lang.String`	`squeezeText(org.w3c.dom.Element node)`	Squeeze the text out of an Element.
`private static XmlVTI`	`xmlVTI(java.io.InputStream xmlResource, java.lang.String rowTag, java.util.ArrayList<java.lang.String> parentTags, java.util.ArrayList<java.lang.String> childTags)`	This is the static method for creating functions from an URL and both parent and child tags
`static XmlVTI`	`xmlVTI(java.lang.String fileName, java.lang.String rowTag, java.lang.String... childTags)`	This is the static method for creating functions from a file name and child tags
`static XmlVTI`	`xmlVTI(java.lang.String fileName, java.lang.String rowTag, java.util.ArrayList<java.lang.String> parentTags, java.util.ArrayList<java.lang.String> childTags)`	This is the static method for creating functions from a file name and both parent and child tags
`static XmlVTI`	`xmlVTIFromURL(java.lang.String urlString, java.lang.String rowTag, java.lang.String... childTags)`	This is the static method for creating functions from an url and child tags
`static XmlVTI`	`xmlVTIFromURL(java.lang.String urlString, java.lang.String rowTag, java.util.ArrayList<java.lang.String> parentTags, java.util.ArrayList<java.lang.String> childTags)`	This is the static method for creating functions from an URL and both parent and child tags

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.sql.ResultSet
updateObject, updateObject, updateObject, updateObject

Methods inherited from class org.apache.derby.vti.StringColumnVTI
findColumn, getAsciiStream, getBigDecimal, getBinaryStream, getBlob, getBoolean, getByte, getBytes, getClob, getColumnCount, getColumnName, getDate, getDouble, getFloat, getInt, getLong, getShort, getString, getTime, getTimestamp, setColumnNames, wasNull

Methods inherited from class org.apache.derby.vti.VTITemplate
absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, deleteRow, first, getArray, getArray, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBlob, getBoolean, getByte, getBytes, getCharacterStream, getCharacterStream, getClob, getConcurrency, getContext, getCursorName, getDate, getDate, getDate, getDouble, getFetchDirection, getFetchSize, getFloat, getHoldability, getInt, getLong, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getObject, getObject, getRef, getRef, getReturnTableSignature, getRow, getRowId, getRowId, getShort, getSQLXML, getSQLXML, getStatement, getString, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, isWrapperFor, last, moveToCurrentRow, moveToInsertRow, notImplemented, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setContext, setFetchDirection, setFetchSize, unwrap, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp

Field Detail

_rowTag
```
private java.lang.String _rowTag
```

_xmlResource

private java.io.InputStream _xmlResource

_rowIdx
```
private int _rowIdx
```

_rowCount
```
private int _rowCount
```

_currentRow
```
private java.lang.String[] _currentRow
```

_builder

private javax.xml.parsers.DocumentBuilder _builder

_rawRows
```
private org.w3c.dom.NodeList _rawRows
```

_firstChildTagIdx
```
private int _firstChildTagIdx
```

Constructor Detail
- XmlVTI
```
public XmlVTI(java.io.InputStream xmlResource,
              java.lang.String rowTag,
              int firstChildTagIdx,
              java.lang.String... columnTags)
```
  Build an XmlVTI.
  
  Parameters:
  
  xmlResource - The xml source as an InputStream.
  
  rowTag - The tag of the master row Element.
  
  firstChildTagIdx - The first (0-based) tag from columnTags which is a child tag.
  
  columnTags - The tags which supply column data; all of the tag positions less than firstChildTagIdx come from Elements which are outer to the rowTag element; the remaining tags, starting at firstChildTagIdx, are tags of attributes or Elements inside the rowTag Element.

Method Detail

xmlVTI

public static XmlVTI xmlVTI(java.lang.String fileName,
                            java.lang.String rowTag,
                            java.lang.String... childTags)
                     throws java.lang.Exception

This is the static method for creating functions from a file name and child tags

Throws:: java.lang.Exception

xmlVTIFromURL

public static XmlVTI xmlVTIFromURL(java.lang.String urlString,
                                   java.lang.String rowTag,
                                   java.lang.String... childTags)
                            throws java.lang.Exception

This is the static method for creating functions from an url and child tags

Throws:: java.lang.Exception

xmlVTI

public static XmlVTI xmlVTI(java.lang.String fileName,
                            java.lang.String rowTag,
                            java.util.ArrayList<java.lang.String> parentTags,
                            java.util.ArrayList<java.lang.String> childTags)
                     throws java.lang.Exception

This is the static method for creating functions from a file name and both parent and child tags

Throws:: java.lang.Exception

xmlVTIFromURL

public static XmlVTI xmlVTIFromURL(java.lang.String urlString,
                                   java.lang.String rowTag,
                                   java.util.ArrayList<java.lang.String> parentTags,
                                   java.util.ArrayList<java.lang.String> childTags)
                            throws java.lang.Exception

This is the static method for creating functions from an URL and both parent and child tags

Throws:: java.lang.Exception

xmlVTI

private static XmlVTI xmlVTI(java.io.InputStream xmlResource,
                             java.lang.String rowTag,
                             java.util.ArrayList<java.lang.String> parentTags,
                             java.util.ArrayList<java.lang.String> childTags)
                      throws java.lang.Exception

This is the static method for creating functions from an URL and both parent and child tags

Throws:: java.lang.Exception

asList

public static java.util.ArrayList<java.lang.String> asList(java.lang.String... cells)

Factory method to create an ArrayList

getRawColumn
```
protected java.lang.String getRawColumn(int columnNumber)
                                 throws java.sql.SQLException
```
Get the string value of the column in the current row identified by the 1-based columnNumber.

Specified by:

getRawColumn in class StringColumnVTI

Throws:

java.sql.SQLException

close

public void close()
           throws java.sql.SQLException

Throws:: java.sql.SQLException

getMetaData
```
public java.sql.ResultSetMetaData getMetaData()
                                       throws java.sql.SQLException
```
Specified by:

getMetaData in interface java.sql.ResultSet

Overrides:

getMetaData in class VTITemplate

Throws:

java.sql.SQLException

public boolean next()
             throws java.sql.SQLException

Throws:: java.sql.SQLException

readRows

private void readRows()
               throws java.lang.Exception

Fault in the list of rows.

Throws:: java.lang.Exception

parseRow

private void parseRow(int rowNumber)
               throws java.lang.Exception

Parse a row into columns.

Throws:: java.lang.Exception

findColumnValue

private java.lang.String findColumnValue(org.w3c.dom.Element rawRow,
                                         int columnNumber)
                                  throws java.lang.Exception

Find the value of a column inside an element. The columnNumber is 0-based.

Throws:: java.lang.Exception

squeezeText

private java.lang.String squeezeText(org.w3c.dom.Element node)
                              throws java.lang.Exception

Squeeze the text out of an Element.

Throws:: java.lang.Exception

Class XmlVTI

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.derby.vti.VTITemplate

Field Summary

Fields inherited from interface java.sql.ResultSet

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.sql.ResultSet

Methods inherited from class org.apache.derby.vti.StringColumnVTI

Methods inherited from class org.apache.derby.vti.VTITemplate

Field Detail

_rowTag

_xmlResource

_rowIdx

_rowCount

_currentRow

_builder

_rawRows

_firstChildTagIdx

Constructor Detail

XmlVTI

Method Detail

xmlVTI

xmlVTIFromURL

xmlVTI

xmlVTIFromURL

xmlVTI

asList

getRawColumn

close

getMetaData

next

readRows

parseRow

findColumnValue

squeezeText