net.sf.farrago.session
Interface FarragoSessionPersonality

All Superinterfaces:
FarragoStreamFactoryProvider
All Known Implementing Classes:
FarragoAutoCalcRulesTest.TestDbSessionPersonality, FarragoDefaultSessionPersonality, FarragoMiniplanPersonalityFactory.FarragoMiniplanSessionPersonality, FarragoTestPersonalityFactory.FarragoTestSessionPersonality, FarragoVolcanoPersonalityFactory.FarragoVolcanoSessionPersonality, LucidDbSessionPersonality

public interface FarragoSessionPersonality
extends FarragoStreamFactoryProvider

FarragoSessionPersonality defines the SPI for plugging in custom FarragoSession behavior.

Version:
$Id: //open/dev/farrago/src/net/sf/farrago/session/FarragoSessionPersonality.java#34 $
Author:
John V. Sichi

Method Summary
 FarragoSessionVariables createInheritedSessionVariables(FarragoSessionVariables variables)
          Creates a set of session variables for use in a cloned session.
 void defineDdlHandlers(FarragoSessionDdlValidator ddlValidator, List<DdlHandler> handlerList)
          See FarragoSessionModelExtension.defineDdlHandlers(net.sf.farrago.session.FarragoSessionDdlValidator, java.util.List).
 void definePlannerListeners(FarragoSessionPlanner planner)
          Defines listeners for events which occur during planning.
 void definePrivileges(FarragoSessionPrivilegeMap map)
          Defines privileges allowed on various object types.
 String getDefaultLocalDataServerName(FarragoSessionStmtValidator stmtValidator)
          Gets the name of the local data server to use for tables when none is specified by CREATE TABLE.
 OJRexImplementorTable getOJRexImplementorTable(FarragoSessionPreparingStmt preparingStmt)
          Gets the implementation table to use for compiling a statement that uses a Java calculator.
 void getRowCounts(ResultSet resultSet, List<Long> rowCounts, TableModificationRelBase.Operation tableModOp)
          Gives this personality the opportunity to retrieve rowcount information returned by a DML operation.
 Class getRuntimeContextClass(FarragoSessionPreparingStmt stmt)
          Determines the class to use for runtime context.
 SqlOperatorTable getSqlOperatorTable(FarragoSessionPreparingStmt preparingStmt)
          Gets the SQL operator table to use for validating a statement.
 boolean isAlterTableAddColumnIncremental()
          Tests whether this session personality implements ALTER TABLE ADD COLUMN in an incremental fashion (only adding on the new column as opposed to reformatting existing rows).
 boolean isJavaUdxRestartable()
          Returns whether a JavaUDX is implemented as a restartable data source.
 boolean isSupportedType(SqlTypeName type)
          Returns whether a type is valid in this database.
 void loadDefaultSessionVariables(FarragoSessionVariables variables)
          Loads variables from the session personality into a session variables object.
<C> C
newComponentImpl(Class<C> componentInterface)
          Gets the component associated with the given Class object from the personality.
 FarragoSessionDdlValidator newDdlValidator(FarragoSessionStmtValidator stmtValidator)
          Creates a new validator for DDL commands.
 JmiQueryProcessor newJmiQueryProcessor(String language)
          Creates a new processor for JMI queries.
 FarragoSessionParser newParser(FarragoSession session)
          Creates a new SQL parser.
 FarragoSessionPlanner newPlanner(FarragoSessionPreparingStmt stmt, boolean init)
          Creates a new planner.
 FarragoSessionPreparingStmt newPreparingStmt(FarragoSessionStmtContext stmtContext, FarragoSessionStmtContext rootStmtContext, FarragoSessionStmtValidator stmtValidator)
          Creates a new preparing statement tied to this session and its underlying database.
 FarragoSessionPreparingStmt newPreparingStmt(FarragoSessionStmtContext stmtContext, FarragoSessionStmtValidator stmtValidator)
          Creates a new preparing statement tied to this session and its underlying database.
 FarragoSessionPreparingStmt newPreparingStmt(FarragoSessionStmtValidator stmtValidator)
          Deprecated. Use the two-arg version instead, passing null for stmtContext.
 FarragoSessionRuntimeContext newRuntimeContext(FarragoSessionRuntimeParams params)
          Creates a new runtime context.
 RelDataTypeFactory newTypeFactory(FarragoRepos repos)
          Creates a new type factory.
 void registerRelMetadataProviders(ChainedRelMetadataProvider chain)
          Gives this personality a chance to register one or more RelMetadataProviders in the chain which will be used to answer relational expression metadata queries during optimization.
 void resetRowCounts(FemAbstractColumnSet table)
          Gives this personality the opportunity to reset rowcount information in the catalog tables for a specified table
 boolean shouldReplacePreserveOriginalSql()
          Tests whether this personality wants original SQL to be preserved for dependent objects where possible during the revalidation triggered by CREATE OR REPLACE.
 boolean supportsFeature(org.eigenbase.resgen.ResourceDefinition feature)
          Tests whether a feature is supported in this personality.
 void updateIndexRoot(FemLocalIndex index, FarragoDataWrapperCache wrapperCache, FarragoSessionIndexMap baseIndexMap, Long newRoot)
          Gives the personality the opportunity to update an index root page when the index is rebuilt
 long updateRowCounts(FarragoSession session, List<String> tableName, List<Long> rowCounts, TableModificationRelBase.Operation tableModOp, FarragoSessionRuntimeContext runningContext)
          Gives this personality the opportunity to update rowcount information in the catalog tables for a specified table as a result of a particular DML operation.
 void validateSessionVariable(FarragoSessionDdlValidator ddlValidator, FarragoSessionVariables variables, String name, String value)
          Checks whether a parameter value is appropriate for a session variable and, if the value is appropriate, sets the session variable.
 
Methods inherited from interface net.sf.farrago.session.FarragoStreamFactoryProvider
registerStreamFactories
 

Method Detail

getSqlOperatorTable

SqlOperatorTable getSqlOperatorTable(FarragoSessionPreparingStmt preparingStmt)
Gets the SQL operator table to use for validating a statement.

Parameters:
preparingStmt - statement being prepared
Returns:
table of builtin SQL operators and functions to use for validation; user-defined functions are not included here

getOJRexImplementorTable

OJRexImplementorTable getOJRexImplementorTable(FarragoSessionPreparingStmt preparingStmt)
Gets the implementation table to use for compiling a statement that uses a Java calculator.

Parameters:
preparingStmt - statement being prepared
Returns:
table of implementations corresponding to result of getSqlOperatorTable(FarragoSessionPreparingStmt)

newComponentImpl

<C> C newComponentImpl(Class<C> componentInterface)
Gets the component associated with the given Class object from the personality. If the personality does not support (or recognize) the component type, it returns null. The returned instance is guaranteed to be of type C or a subclass.

Parameters:
componentInterface - the interface desired
Returns:
an implementation of componentInterface or null

getDefaultLocalDataServerName

String getDefaultLocalDataServerName(FarragoSessionStmtValidator stmtValidator)
Gets the name of the local data server to use for tables when none is specified by CREATE TABLE.

Parameters:
stmtValidator - validator for statement being prepared
Returns:
server name

isAlterTableAddColumnIncremental

boolean isAlterTableAddColumnIncremental()
Tests whether this session personality implements ALTER TABLE ADD COLUMN in an incremental fashion (only adding on the new column as opposed to reformatting existing rows). For example, a column store can just create a new vertical partition; a smart row store may be able to transform old tuple formats during queries by filling in default values on the fly.

Returns:
true iff the incremental optimization is implemented

isJavaUdxRestartable

boolean isJavaUdxRestartable()
Returns whether a JavaUDX is implemented as a restartable data source.

Returns:
true if a JavaUDXRel implementation is restartable.

newParser

FarragoSessionParser newParser(FarragoSession session)
Creates a new SQL parser.

Parameters:
session - session which will use the parser
Returns:
new parser

newPreparingStmt

FarragoSessionPreparingStmt newPreparingStmt(FarragoSessionStmtContext stmtContext,
                                             FarragoSessionStmtContext rootStmtContext,
                                             FarragoSessionStmtValidator stmtValidator)
Creates a new preparing statement tied to this session and its underlying database. Used to construct and implement an internal query plan.

Parameters:
stmtContext - embracing stmt context, if any; otherwise, null.
rootStmtContext - the root stmt context
stmtValidator - generic stmt validator
Returns:
a new FarragoSessionPreparingStmt.

newPreparingStmt

FarragoSessionPreparingStmt newPreparingStmt(FarragoSessionStmtContext stmtContext,
                                             FarragoSessionStmtValidator stmtValidator)
Creates a new preparing statement tied to this session and its underlying database. Used to construct and implement an internal query plan.

Parameters:
stmtContext - embracing stmt context, if any; otherwise, null.
stmtValidator - generic stmt validator
Returns:
a new FarragoSessionPreparingStmt.

newPreparingStmt

FarragoSessionPreparingStmt newPreparingStmt(FarragoSessionStmtValidator stmtValidator)
Deprecated. Use the two-arg version instead, passing null for stmtContext.


newDdlValidator

FarragoSessionDdlValidator newDdlValidator(FarragoSessionStmtValidator stmtValidator)
Creates a new validator for DDL commands.

Parameters:
stmtValidator - generic stmt validator
Returns:
new validator

defineDdlHandlers

void defineDdlHandlers(FarragoSessionDdlValidator ddlValidator,
                       List<DdlHandler> handlerList)
See FarragoSessionModelExtension.defineDdlHandlers(net.sf.farrago.session.FarragoSessionDdlValidator, java.util.List).

Parameters:
ddlValidator - validator which will invoke handlers
handlerList - receives handler objects in order in which they should be invoked

definePrivileges

void definePrivileges(FarragoSessionPrivilegeMap map)
Defines privileges allowed on various object types.

Parameters:
map - receives allowed privileges

newPlanner

FarragoSessionPlanner newPlanner(FarragoSessionPreparingStmt stmt,
                                 boolean init)
Creates a new planner.

Parameters:
stmt - stmt on whose behalf planner will operate
init - whether to initialize default rules in new planner
Returns:
new planner

definePlannerListeners

void definePlannerListeners(FarragoSessionPlanner planner)
Defines listeners for events which occur during planning.

Parameters:
planner - planner to which listeners should be added

getRuntimeContextClass

Class getRuntimeContextClass(FarragoSessionPreparingStmt stmt)
Determines the class to use for runtime context.

Parameters:
stmt - stmt on whose behalf planner will operate
Returns:
runtime context class, which must implement FarragoSessionRuntimeContext

newRuntimeContext

FarragoSessionRuntimeContext newRuntimeContext(FarragoSessionRuntimeParams params)
Creates a new runtime context. The object returned must be assignable to the result of getRuntimeContextClass().

Parameters:
params - context initialization parameters
Returns:
new context

newTypeFactory

RelDataTypeFactory newTypeFactory(FarragoRepos repos)
Creates a new type factory.

Parameters:
repos - a repository containing Farrago metadata
Returns:
a new type factory

loadDefaultSessionVariables

void loadDefaultSessionVariables(FarragoSessionVariables variables)
Loads variables from the session personality into a session variables object. Each personality uses on its own variables. This method allows the personality to declare its variables and set default values for them. If any variables already have values, then they will not be overwritten.

This method should be called when initializing a new session or when loading a new session personality for an existing session. This method "leaves a mark", as it has the side effect of permanently updating the session variables. Even if the session personality is swapped out, the changes will remain.

Parameters:
variables - the session variables object

createInheritedSessionVariables

FarragoSessionVariables createInheritedSessionVariables(FarragoSessionVariables variables)
Creates a set of session variables for use in a cloned session. Default implementation is to just return variables.cloneVariables(), but personalities may override, e.g. to reset some variables which should never be inherited.

Parameters:
variables - set of variables to be inherited
Returns:
result of variable inheritance

validateSessionVariable

void validateSessionVariable(FarragoSessionDdlValidator ddlValidator,
                             FarragoSessionVariables variables,
                             String name,
                             String value)
Checks whether a parameter value is appropriate for a session variable and, if the value is appropriate, sets the session variable. If an error is encountered, then the method throws an EigenbaseException. Possible errors include when no session variable has the specified name, when a non-numeric value was specified for a numeric variable, when a directory does not exist, or other errors.

Parameters:
ddlValidator - a ddl statement validator
variables - a session variables object
name - name of the session variable to be validated
value - value to set for the session variable

newJmiQueryProcessor

JmiQueryProcessor newJmiQueryProcessor(String language)
Creates a new processor for JMI queries.

Parameters:
language - query language (e.g. "LURQL")
Returns:
query processor, or null if language not supported

isSupportedType

boolean isSupportedType(SqlTypeName type)
Returns whether a type is valid in this database.

Parameters:
type - Type
Returns:
whether a type is valid in this database

supportsFeature

boolean supportsFeature(org.eigenbase.resgen.ResourceDefinition feature)
Tests whether a feature is supported in this personality.

Parameters:
feature - EigenbaseResource resource definition representing the feature to be tested
Returns:
true iff feature is supported

shouldReplacePreserveOriginalSql

boolean shouldReplacePreserveOriginalSql()
Tests whether this personality wants original SQL to be preserved for dependent objects where possible during the revalidation triggered by CREATE OR REPLACE.

Returns:
true iff an attempt should be made to preserve original SQL

registerRelMetadataProviders

void registerRelMetadataProviders(ChainedRelMetadataProvider chain)
Gives this personality a chance to register one or more RelMetadataProviders in the chain which will be used to answer relational expression metadata queries during optimization. Personalities which define their own relational expressions will generally need to supply corresponding metadata providers.

Parameters:
chain - receives personality's custom providers, if any

getRowCounts

void getRowCounts(ResultSet resultSet,
                  List<Long> rowCounts,
                  TableModificationRelBase.Operation tableModOp)
                  throws SQLException
Gives this personality the opportunity to retrieve rowcount information returned by a DML operation.

Parameters:
resultSet - result set returned by DML operation
rowCounts - list of rowcounts returned by the DML operation
tableModOp - table modification operation that caused the rowcounts to be modified
Throws:
SQLException

updateRowCounts

long updateRowCounts(FarragoSession session,
                     List<String> tableName,
                     List<Long> rowCounts,
                     TableModificationRelBase.Operation tableModOp,
                     FarragoSessionRuntimeContext runningContext)
Gives this personality the opportunity to update rowcount information in the catalog tables for a specified table as a result of a particular DML operation.

Parameters:
session - session that needs to update rowcounts
tableName - fully qualified table name for which rowcounts will be updated
rowCounts - list of row counts returned by the DML statement
tableModOp - table modification operation that caused the rowcounts to be modified
runningContext - the currently running session context.
Returns:
number of rows affected by the DML operation

resetRowCounts

void resetRowCounts(FemAbstractColumnSet table)
Gives this personality the opportunity to reset rowcount information in the catalog tables for a specified table

Parameters:
table - column set corresponding to table

updateIndexRoot

void updateIndexRoot(FemLocalIndex index,
                     FarragoDataWrapperCache wrapperCache,
                     FarragoSessionIndexMap baseIndexMap,
                     Long newRoot)
Gives the personality the opportunity to update an index root page when the index is rebuilt

Parameters:
index - index whose root is being updated
wrapperCache - cache for looking up data wrappers
baseIndexMap - map for managing index storage
newRoot - index's new root page