Interface Query

public abstract interface Query

Interface to a query used or created by a CustomTag. A query contains tabular data organized by named columns and rows

Method Summary
int
addRow() 
Adds a new row to the query.
int
getColumnIndex(String name) 
Retrieves the index of a column given its name.
String[]
getColumns() 
Retrieves a list of the column names contained in the query.
String
getData(int iRow, int iCol) 
Retrieves a data element from a row and column of the query.
String
getName() 
Retrieves the name of the query.
int
getRowCount() 
Retrieves the number of rows in the query.
void
setData(int iRow, int iCol, 
String data) 
Sets a data element within a row and column of the query.

Method Detail

getName

public String getName()

Retrieves the name of the query.

The following example retrieves the name of the query and writes it back to the user:

   Query query = request.getQuery() ;
   response.write( "The query name is: " + query.getName() ) ; 

Returns:

The name of the query.

getRowCount

public int getRowCount()

Retrieves the number of rows in the query.

The following example retrieves the number of rows in a query and writes it back to the user:

   Query query = request.getQuery() ;
   int rows = query.getRowCount() ;
   response.write( "The number of rows in the query is " 
                      + Integer.toString(rows) ) ; 

Returns:

The number of rows contained in the query.

getColumnIndex

public int getColumnIndex(String name)

Retrieves the index of a column given its name.

The following example retrieves the index of the EMAIL column and uses it to output a list of the addresses contained in the column:

   // Get the index of the EMAIL column
   int iEMail = query.getColumnIndex( "EMAIL" ) ;

   // Iterate over the query and output list of addresses
   int nRows = query.getRowCount() ;
   for( int iRow=1; iRow<=nRows; iRow++ )
   {
      response.write( query.getData( iRow, iEMail ) + "<BR>" ) ;
   } 

Parameters:

name -- Name of column to get index of (lookup is case insensitive)

Returns:

The index of the column (returns -1 if no such column exists).

See Also:

getColumns, getData

getColumns

public String[] getColumns()

Retrieves a list of the column names contained in the query.

The following example retrieves the array of columns and then iterates over the list, writing each column name back to the user:

   // Get the list of columns from the query
   String[] columns = query.getColumns() ;
   int nNumColumns = columns.length ;                    

   // Print the list of columns to the user
   response.write( "Columns in query: " ) ;
   for( int i=0; i<nNumColumns; i++ )
   {
      response.write( columns[i] + " " ) ;
   } 

Returns:

An array of strings containing the names of the columns in the query.

getData

public String getData(int iRow,
                      int iCol)
               throws IndexOutOfBoundsException

Retrieves a data element from a row and column of the query. Row and column indexes begin with 1. You can determine the number of rows in the query by calling getRowCount. You can determine the columns in the query by calling getColumns.

The following example iterates over the rows of the query and writes the data back to the user in a simple, space-delimited format:

   int iRow, iCol ;
   int nNumCols = query.getColumns().length ;
   int nNumRows = query.getRowCount() ;
   for ( iRow=1; iRow<=nNumRows; iRow++ )
   {
      for ( iCol=1; iCol<=nNumCols; iCol++ )
      {
         response.write( query.getData( iRow, iCol ) + " " ) ;
      }
      response.write( "<BR>" ) ;
   } 

Parameters:

iRow -- Row to retrieve data from (1-based)

iCol -- Column to retrieve data from (1-based)

Returns:

The value of the requested data element.

Throws:

IndexOutOfBoundsException - If an invalid index is passed to the method.

See Also:

setData,     addRow

addRow

public int addRow()

Adds a new row to the query. Call this method each time you want to append a row to the query.

The following example demonstrates the addition of 2 rows to a query that has 3 columns ('City', 'State', and 'Zip'):

   // Define column indexes
   int iCity = 1, iState = 2, iZip = 3 ;
      
   // First row
   int iRow = query.addRow() ;
   query.setData( iRow, iCity, "Minneapolis" ) ;
   query.setData( iRow, iState, "MN" ) ;
   query.setData( iRow, iZip, "55345" ) ;

   // Second row
   iRow = query.addRow() ;
   query.setData( iRow, iCity, "St. Paul" ) ;
   query.setData( iRow, iState, "MN" ) ;
   query.setData( iRow, iZip, "55105" ) ; 

Returns:

The index of the row that was appended to the query.

See Also:

setData,     getData

setData

public void setData(int iRow,
                    int iCol,
                    String data)
             throws IndexOutOfBoundsException

Sets a data element within a row and column of the query. Row and column indexes begin with 1. Before calling setData for a given row you should be sure to call addRow and use the return value as the row index for your call to setData.

The following example demonstrates the addition of 2 rows to a query that has 3 columns ('City', 'State', and 'Zip'):

   // Define column indexes
   int iCity = 1, iState = 2, iZip = 3 ;
      
   // First row
   int iRow = query.addRow() ;
   query.setData( iRow, iCity, "Minneapolis" ) ;
   query.setData( iRow, iState, "MN" ) ;
   query.setData( iRow, iZip, "55345" ) ;

   // Second row
   iRow = query.addRow() ;
   query.setData( iRow, iCity, "St. Paul" ) ;
   query.setData( iRow, iState, "MN" ) ;
   query.setData( iRow, iZip, "55105" ) ; 

Parameters:

iRow -- Row of data element to set (1-based)

iCol -- Column of data element to set (1-based)

data -- New value for data element

Throws:

IndexOutOfBoundsException -- If an invalid index is passed to the method.

See Also:

getData,     addRow