VirtualTableHandler

```
public interface VirtualTableHandler
```
The interface that must be implemented by the handler for a virtual table. The name of the class that implements the handler for a virtual table is specified through the ProgID property of the CmVirtualTableDefinition defining the table. The handler implementation can be checked in as a CodeModule object, or can be placed in the classpath of the application server where the Content Engine is running.

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static class`	`VirtualTableHandler.VirtualColumnDescription` An object describing a virtual column materialised by the handler.
`static class`	`VirtualTableHandler.VirtualRow` An object representing a virtual row, consisting of the joining value for that row and the additonal column values materialised for that row.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`OPTION_ACCESS_REQUIRED` Option identifiers.
`static int`	`OPTION_MAX_FETCH`
`static int`	`OPTION_MAX_FILTER`
`static int`	`OPTION_PAGING_SUPPORTED`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`close()` Notifies the handler that this instance will not be used any further allowing it to clean up any resources it has allocated.
`java.util.List<VirtualTableHandler.VirtualRow>`	`fetchRows(int maxResults, boolean pagedSearch, java.util.Set<java.lang.String> selectedProperties, java.lang.String continueFrom, long timeLimit)` Fetch a set of rows from the virtual table.
`java.util.List<VirtualTableHandler.VirtualRow>`	`filterRows(java.util.List<Properties> requiredPropValues, java.util.Set<java.lang.String> selectedProperties, long timeLimit)` Filter a list of candidate rows obtained via a DB-first query and subjected to security filtering to eliminate those which are not present in the virtual table, and provide additional property (column) values for those which are.
`java.lang.String`	`getContinuation()` Requests the handler to deliver a continuation string which can be used to continue paging through the virtual table with a subsequent fetchRows call.
`int`	`getOption(int option)` Return information regarding a particular requirement or optional feature of the handler.
`java.lang.String[]`	`getRequiredProperties()` Return the list of symbolic names properties that the handler requires of objects of the underlying class in order to perform DB-first row filtering.
`java.lang.String`	`getTableName()`
`VirtualTableHandler.VirtualColumnDescription[]`	`initialize(CmVirtualTableDefinition definition, ClassDescription queriedClass, java.lang.String rootClass, java.lang.Object[] parameters)` Initialize a handler instance in preparation for existing a query containing a virtual table expression.
`void`	`rowConsumed(VirtualTableHandler.VirtualRow consumedRow)` Informs the handler that a row has been consumed from the results returned by a preceding fetchRows call.

- Field Detail
  - OPTION_ACCESS_REQUIRED
```
static final int OPTION_ACCESS_REQUIRED
```
    Option identifiers.
    
    See Also:
    
    Constant Field Values
  - OPTION_PAGING_SUPPORTED
```
static final int OPTION_PAGING_SUPPORTED
```
    See Also:
    
    Constant Field Values
  - OPTION_MAX_FETCH
```
static final int OPTION_MAX_FETCH
```
    See Also:
    
    Constant Field Values
  - OPTION_MAX_FILTER
```
static final int OPTION_MAX_FILTER
```
    See Also:
    
    Constant Field Values
- Method Detail
  - getTableName
```
java.lang.String getTableName()
```
    Returns:
    
    The name of the virtual table materialised by this handler, in the form ::
  - initialize
```
VirtualTableHandler.VirtualColumnDescription[] initialize(CmVirtualTableDefinition definition,
                                                          ClassDescription queriedClass,
                                                          java.lang.String rootClass,
                                                          java.lang.Object[] parameters)
```
    Initialize a handler instance in preparation for existing a query containing a virtual table expression.
    
    Parameters:
    
    definition - The CmVirtualTableDefinition instance defining the virtual table, from which the handler can obtain configuration settings.
    
    queriedClass - The ClassDescription instance describing the underlying class of the virtual table expression.
    
    rootClass - The symbolic name of the system root class from which the queried class is derived.
    
    parameters - The values of the parameters specified in the virtual table expression.
    
    Returns:
    
    An array of descriptions of the additional columns materialised for the virtual table.
  - getRequiredProperties
```
java.lang.String[] getRequiredProperties()
```
    Return the list of symbolic names properties that the handler requires of objects of the underlying class in order to perform DB-first row filtering. The array returned must contain at leadt one entry, naming the joining property at index 0 in the array.
    
    Returns:
    
    Array of property symbolic names.
  - getOption
```
int getOption(int option)
```
    Return information regarding a particular requirement or optional feature of the handler.
    
    Parameters:
    
    option - An integer value identifying the option being queried. One of the OPTION_ values defined by this interface.
    
    Returns:
    
    An integer value reflecting the handler's requirement or support for the specified option. The handler should return 0 for any unrecognized option.
  - fetchRows
```
java.util.List<VirtualTableHandler.VirtualRow> fetchRows(int maxResults,
                                                         boolean pagedSearch,
                                                         java.util.Set<java.lang.String> selectedProperties,
                                                         java.lang.String continueFrom,
                                                         long timeLimit)
```
    Fetch a set of rows from the virtual table.
    
    Parameters:
    
    maxResults - The maximum number of rows to return. This will not exceed the value of the option OPTION_MAX_ROWS returned by the handler. If fewer than the maximum is returned that will be taken as signalling that the end of the table has been reached.
    
    pagedSearch - Boolean indicating if this is a paged or non-paged search. This will be false if the handler does not support paging. If the value is true the handler is obligated to retain sufficient information from the results returned to allow getContinuation to formulate a continuation string.
    
    selectedProperties - An array of the additional properties (columns) for which values should be returned. This will be based on the SELECT list of the query, so may be empty (but the parameter will never be null).
    
    continueFrom - If non-null requires the handler to return rows starting immediately after a previously returned row, as specified by the result of a getContinuation call made following a previous fetchRows. This will be null if the handler does not support paging (option OPTON_PAGING_SUPPORTED was returned as 0) or this is the start of a new search.
    
    timeLimit - If non-zero specifies a period in milliseconds after which the handler should attempt to abort the operation.
    
    Returns:
    
    A list of VirtualRows.
  - filterRows
```
java.util.List<VirtualTableHandler.VirtualRow> filterRows(java.util.List<Properties> requiredPropValues,
                                                          java.util.Set<java.lang.String> selectedProperties,
                                                          long timeLimit)
```
    Filter a list of candidate rows obtained via a DB-first query and subjected to security filtering to eliminate those which are not present in the virtual table, and provide additional property (column) values for those which are. Each candidate row is identified by a Properties collection each of which will contain at least the properties specified as required by the handler and in particular having a non-null value for the joining property.
    
    Parameters:
    
    requiredPropValues - A list of Properties collections each containing values of the required properties.
    
    selectedProperties - An array of the additional properties (columns) for which values should be returned. This will be based on the SELECT list of the query, so may be empty (but the parameter will never be null).
    
    timeLimit - If non-zero specifies a period in milliseconds after which the handler should attempt to abort the operation.
    
    Returns:
    
    A list of VirtualRows. The order of rows in the list must match that of that reflected by the join values in input list. although usually with some omissions.
  - rowConsumed
```
void rowConsumed(VirtualTableHandler.VirtualRow consumedRow)
```
    Informs the handler that a row has been consumed from the results returned by a preceding fetchRows call. Tha handler can use this to inform building a continuation string. This method will not be called for a non-paged search or if the handler does not support paging.
    
    Parameters:
    
    consumedRow - The VirtualRow object for the row consumed.
  - getContinuation
```
java.lang.String getContinuation()
```
    Requests the handler to deliver a continuation string which can be used to continue paging through the virtual table with a subsequent fetchRows call. The continuation string should be such that the next fetch will start at the row immediately following the last consumed per a call to rowConsumed or, if no such calls have been made, from the row immediately following the last row of the entire set returned by the previous fetchRows. This method will not be called for a non-paged search or if the handler does not support paging.
    
    Returns:
    
    A continuation string which can be passed in to a subsequent fetchRows call.
  - close
```
void close()
```
    Notifies the handler that this instance will not be used any further allowing it to clean up any resources it has allocated.

OPTION_ACCESS_REQUIRED

OPTION_PAGING_SUPPORTED

OPTION_MAX_FETCH

OPTION_MAX_FILTER

getTableName

initialize

getRequiredProperties

getOption

fetchRows

filterRows

rowConsumed

getContinuation

close