Class QueryProviderBase<RowType>

This is the base class for ArchiveProviders that use a database query to get their data. Other ways of making archive providers exist, such as , where the data source is something else and the data are simply buffered by the base class.

Inheritance
System.Object
ExtensibleColumnsBase
QueryProviderBase<RowType>
ListItemsProvider
ParticipantsSubProviderBase
ProjectMemberAssociateProvider
QuoteApprovalProvider
RelationQueryProviderBase<SourceExtenderType, TargetExtenderType>
ReportLabelLayoutProvider
SelectionCombinedContactProviderBase<Extender>
TicketNotificationProvider
TimeZonesProvider
TypedQueryProviderBase<RowType, RootExtender>
Inherited Members
Namespace: SuperOffice.CRM.ArchiveLists
Assembly: SoDataBase.dll
Syntax
public abstract class QueryProviderBase<RowType> : ExtensibleColumnsBase, IArchiveProviderQueryMapping, IArchiveQueryProvider, IArchiveProviderExtensible, IArchiveProvider, IArchiveProviderHasRows, IArchiveProviderHasColumns, IArchiveProviderHasEntities, IPlugin where RowType : ArchiveRow, new()
Type Parameters
Name Description
RowType
Remarks

Classes derived from this class will generally have the following structure:

    An archive provider can have functionality ranging from trivial to extremely complex, and there are a number of ways to compose, extend and factor the query buildup and processing. Refer to the SDK documentation for more details.

    Constructors

    QueryProviderBase()

    Declaration
    protected QueryProviderBase()

    Fields

    _colGetAllRows

    Dummy column present in all archives; used in restrictions to specifically request a non-restricted read from the database.

    Declaration
    protected ArchiveColumnInfo _colGetAllRows
    Field Value
    Type Description
    ArchiveColumnInfo

    _colGetNoRows

    Declaration
    protected ArchiveColumnInfo _colGetNoRows
    Field Value
    Type Description
    ArchiveColumnInfo

    _pageNumber

    Declaration
    protected int _pageNumber
    Field Value
    Type Description
    System.Int32

    _pageSize

    Declaration
    protected int _pageSize
    Field Value
    Type Description
    System.Int32

    Properties

    DropTablesFromPhaseTwo

    The fields in this enumeration will be dropped from a Phase Two query; that may also cause one or more tables to be dropped. A useful optimization in a very small number of cases (where fields/joins are only used for Phase One/AcceptRow processing)

    Declaration
    protected virtual TableInfo[] DropTablesFromPhaseTwo { get; }
    Property Value
    Type Description
    TableInfo[]

    HaveReadToEnd

    If all subproviders have been read all the way, then this is set to true

    Declaration
    protected bool HaveReadToEnd { get; }
    Property Value
    Type Description
    System.Boolean

    InhibitDistinctPrimaryKeys

    Override this property and return TRUE if you wish to disable the check for distinct primary keys. This will save some time and space, at the cost of potential duplicate rows that would otherwise have been discarded

    Declaration
    public virtual bool InhibitDistinctPrimaryKeys { get; }
    Property Value
    Type Description
    System.Boolean

    InhibitTwoPhaseQuery

    Queries are usually run in two phases, one to determine the result set and the other to actually include all joins and fields. This can be inhibited if needed

    Declaration
    protected bool InhibitTwoPhaseQuery { get; set; }
    Property Value
    Type Description
    System.Boolean

    OrderBySlots

    The Order By storage system of this archive provider

    Declaration
    public override OrderByStorage OrderBySlots { get; }
    Property Value
    Type Description
    OrderByStorage
    Overrides

    PrimaryKey

    The primary key, whose values are used by the duplicate eliminator

    Declaration
    protected FieldInfo PrimaryKey { get; set; }
    Property Value
    Type Description
    FieldInfo

    PrimaryTable

    The primary table of this archive provider, from the derived class

    Declaration
    public abstract TableInfo PrimaryTable { get; }
    Property Value
    Type Description
    TableInfo

    Query

    The main query of this archive provider, from the derived class

    Declaration
    public abstract ArchiveSelect Query { get; }
    Property Value
    Type Description
    ArchiveSelect

    RootExtenders

    Implement this property to return the extender(s) that form the root of the query tree, or null if that is not meaningful. This property is used by the dynamic column processing, which will fail and throw an exception if null is returned here (no problem if dynamic column syntax is not used)

    Declaration
    protected abstract List<IArchiveExtender> RootExtenders { get; }
    Property Value
    Type Description
    System.Collections.Generic.List<IArchiveExtender>

    RootQuery

    The main query of this archive provider

    Declaration
    public override ArchiveSelect RootQuery { get; }
    Property Value
    Type Description
    ArchiveSelect
    Overrides

    TableToExtend

    The primary table of this archive provider

    Declaration
    public override TableInfo TableToExtend { get; }
    Property Value
    Type Description
    TableInfo
    Overrides

    ValueOverrides

    Declaration
    protected Dictionary<string, string> ValueOverrides { get; }
    Property Value
    Type Description
    System.Collections.Generic.Dictionary<System.String, System.String>

    Methods

    AcceptRow(SoDataReader)

    Decide whether the current row of the passed-in _reader should be accepted or not. If false is returned, this row is skipped by the base class and never seen by the client. This method is called very early, before any ArchiveRow population, and can only rely on fields directly accessible in the Reader. On the other hand, that makes is reasonably cheap to skip rows.

    If you implement this method, you MUST aslo implement RequiredPhaseOneFields() to tell the query rewriter about fields you need, otherwise they will not be present in the phase one query and you will crash.

    Declaration
    protected virtual bool AcceptRow(SoDataReader reader)
    Parameters
    Type Name Description
    SoDataReader reader
    Returns
    Type Description
    System.Boolean

    true if the current row should be further processed

    AddInhibitedStyleHint(String)

    Add a style hint to the list of style hints that should be hidden (not be present in the final result rows)

    Declaration
    public void AddInhibitedStyleHint(string stylehint)
    Parameters
    Type Name Description
    System.String stylehint

    Close()

    Call this method after the last desired row has been read; this gives the provider the chance to close and free any underlying queries.

    Declaration
    public virtual void Close()

    ConvertToTypedRows(IEnumerable<ArchiveRow>)

    Convert a generic ArchiveRow into some typed subclass, provided the passed-in rows are actually castable

    Declaration
    protected IEnumerable<RowType> ConvertToTypedRows(IEnumerable<ArchiveRow> genericRows)
    Parameters
    Type Name Description
    System.Collections.Generic.IEnumerable<ArchiveRow> genericRows

    Enumerable of generic rows that are actually a typed subclass
    Returns
    Type Description
    System.Collections.Generic.IEnumerable<RowType>

    Enumerable of case, typed rows

    CreateArchiveRow(String, Int32)

    Create the archive row object. Providers that offer a strongly typed interface should override this method and create their strongly typed row instead of leaving this generic implementation to make the generic one.

    Declaration
    protected virtual RowType CreateArchiveRow(string entityName, int primaryKey)
    Parameters
    Type Name Description
    System.String entityName

    name of entity represented by this row
    System.Int32 primaryKey

    Primary key value of this row
    Returns
    Type Description
    RowType

    Empty row

    GetAllExtenders()

    Declaration
    public IEnumerable<IArchiveExtender> GetAllExtenders()
    Returns
    Type Description
    System.Collections.Generic.IEnumerable<IArchiveExtender>

    GetAvailableEntities()

    Get all entities declared by this provider and its extenders

    Declaration
    public virtual List<ArchiveRowTypeInfo> GetAvailableEntities()
    Returns
    Type Description
    System.Collections.Generic.List<ArchiveRowTypeInfo>

    List of available entities

    GetEntityName(SoDataReader)

    Return the entity name of the current row. The default implementation statically assigns the name of the first registered entity to all rows. Subclasses may override this method if they wish to set other entity names, possibly dependent on data.

    Declaration
    protected virtual string GetEntityName(SoDataReader _reader)
    Parameters
    Type Name Description
    SoDataReader _reader

    _reader with the current data row
    Returns
    Type Description
    System.String

    Entity name

    GetFinalRowCount()

    Actual number of rows in query, valid only when HaveReadToEnd = true; otherwise you get -1

    Declaration
    protected int GetFinalRowCount()
    Returns
    Type Description
    System.Int32

    GetReader(String)

    Declaration
    public virtual IDataReader GetReader(string options)
    Parameters
    Type Name Description
    System.String options
    Returns
    Type Description
    System.Data.IDataReader

    GetResultInformation()

    Get additional information about the result, such as row count or other optional items. This method should be called some time after GetRows, but before Close. Delaying calls to this method as long as possible will give its (asynchronous) internal counterpart more time to complete and lessen the response-time impact of calling it.

    Declaration
    public ArchiveResultInformation GetResultInformation()
    Returns
    Type Description
    ArchiveResultInformation

    GetRows(String)

    Pass the built-up query to the database; perform paging; and pass populated rows back to the caller.

    Declaration
    public virtual IEnumerable<ArchiveRow> GetRows(string options)
    Parameters
    Type Name Description
    System.String options
    Returns
    Type Description
    System.Collections.Generic.IEnumerable<ArchiveRow>
    Remarks

    This method calls the following derived-class overrides, in the following order:

    HandleDynamicExtenders(IArchiveExtender)

    Declaration
    protected virtual void HandleDynamicExtenders(IArchiveExtender dynamicTree)
    Parameters
    Type Name Description
    IArchiveExtender dynamicTree

    InnerMapFields()

    Override this method to map query fields to columns, add additional return fields to the query, and set up custom restriction handling

    Declaration
    public virtual void InnerMapFields()

    InnerSetRestriction(ArchiveRestrictionInfo[])

    Override this method to implement custom processing during SetRestriction, without killing the default implementation

    Declaration
    public virtual bool InnerSetRestriction(ArchiveRestrictionInfo[] restrictions)
    Parameters
    Type Name Description
    ArchiveRestrictionInfo[] restrictions

    Incoming array of restrictions
    Returns
    Type Description
    System.Boolean

    True if at least one active restriction matched a known column and was processed

    OverrideValueIfBlank(ArchiveRow, String, String)

    Declaration
    protected bool OverrideValueIfBlank(ArchiveRow row, string columnToOverride, string alternativeSource)
    Parameters
    Type Name Description
    ArchiveRow row
    System.String columnToOverride
    System.String alternativeSource
    Returns
    Type Description
    System.Boolean

    PostProcessQuery()

    This method is called after ModifyQuery has been called on all extenders, but before the query is executed. It is used for processing that needs the query to be 'complete' from the extenders, and gives the opportunity to tweak it, for instance by adding return fields needed for some particular functionality.

    Declaration
    public virtual void PostProcessQuery()

    PostProcessRow(SoDataReader, ArchiveRow)

    This method is a hook that can be used by derived classes to post-process rows. It is called after all extenders have fetched their data and populated the row.

    Declaration
    protected virtual void PostProcessRow(SoDataReader _reader, ArchiveRow row)
    Parameters
    Type Name Description
    SoDataReader _reader
    ArchiveRow row

    RegisterEntity(ArchiveRowTypeInfo)

    Register an entity on this provider

    Declaration
    protected ArchiveRowTypeInfo RegisterEntity(ArchiveRowTypeInfo entity)
    Parameters
    Type Name Description
    ArchiveRowTypeInfo entity

    Entity to register
    Returns
    Type Description
    ArchiveRowTypeInfo

    The same entity, so you can go on doing things to it

    RequiredPhaseOneFields()

    Return the FieldInfo fields needed by AcceptRow(SoDataReader), so that the query rewriter does not drop them. Implement this method IFF you implement AcceptRow.

    Declaration
    protected virtual FieldInfo[] RequiredPhaseOneFields()
    Returns
    Type Description
    FieldInfo[]

    SetDesiredColumns(String[])

    Set the desired columns, by saving them in an internal data structures. Duplicates are gracefully ignored.

    Declaration
    public override void SetDesiredColumns(params string[] columnIds)
    Parameters
    Type Name Description
    System.String[] columnIds
    Overrides

    SetDesiredEntities(String[])

    Set the desired entities

    Declaration
    public virtual void SetDesiredEntities(params string[] entities)
    Parameters
    Type Name Description
    System.String[] entities

    Names of desired entities

    SetOrderBy(ArchiveOrderByInfo[])

    Declaration
    public override void SetOrderBy(ArchiveOrderByInfo[] orderBy)
    Parameters
    Type Name Description
    ArchiveOrderByInfo[] orderBy
    Overrides

    SetPagingInfo(Int32, Int32)

    Verify the paging information, and set page size and number

    Declaration
    public void SetPagingInfo(int pageSize, int pageNumber)
    Parameters
    Type Name Description
    System.Int32 pageSize

    Page size in rows, 1-2000 or int.MaxValue to disable paging
    System.Int32 pageNumber

    0-based page number

    SetRestriction(ArchiveRestrictionInfo[])

    Set the restriction by calling the base class and InnerSetRestriction; take this opportunity to note that a restriction has actually been set, so we can report cases of totally missing restrictions (which is not acceptable as it might end up fetching the whole database)

    Declaration
    public override bool SetRestriction(params ArchiveRestrictionInfo[] restrictions)
    Parameters
    Type Name Description
    ArchiveRestrictionInfo[] restrictions
    Returns
    Type Description
    System.Boolean
    Overrides

    Implements

    Extension Methods

    EnumUtil.MapEnums<From, To>(From)