1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Class declaration for CDiagPluginExecPlanImpl

    15 *

    16 */

    17 

    18 

    19 #ifndef DIAGPLUGINEXECPLANIMPL_H

    20 #define DIAGPLUGINEXECPLANIMPL_H

    21 

    22 // SYSTEM INCLUDE FILES

    23 #include <e32base.h>                    // CBase

    24 #include <DiagPluginExecPlan.h>         // MDiagPluginExecPlan

    25 #include <DiagResultsDatabaseItem.h>    // CDiagResultsDatabaseItem::TResult

    26 

    27 // USER INCLUDE FILES

    28 #include "diagexecplanentryimpl.h"      // TDiagPluginExecPlanImpl::TType

    29 

    30 // FORWARD DECLARATION

    31 class MDiagPlugin;

    32 class MDiagSuitePlugin;

    33 class MDiagEngineCommon;

    34 class CDiagPluginPool;

    35 class RDiagResultsDatabaseRecord;

    36 class TDiagEngineConfig;

    37 struct TTransitionStackEntry;

    38 

    39 template <class T, TBool StackOwnsEntry>

    40 class CStack;

    41 

    42 /**

    43 *  Diagnostics Plugin Execution Plan

    44 *

    45 *  This class provides interface to access execution plan.

    46 *  It also provides interface to modify execution plan.

    47 *  A cursor to currently executing item is also maintained.

    48 *

    49 * @since S60 v5.0

    50 *

    51 */

    52 NONSHARABLE_CLASS( CDiagPluginExecPlanImpl ) : public CActive,

    53                                                public MDiagPluginExecPlan

    54     {

    55 public: 

    56     /**

    57     * Two-phase constructor

    58     *

    59     * @param aEngine - Reference to diagnostics engine.

    60     * @param aEngineConfig - Engine configuration information.

    61     * @param aEntryObserver - Reference to entry observer.

    62     * @return new instance of CDiagPluginExecPlanImpl

    63     */

    64     static CDiagPluginExecPlanImpl* NewL( MDiagEngineCommon& aEngine,

    65                                           const TDiagEngineConfig& aEngineConfig,

    66                                           MDiagExecPlanEntryImplObserver& aEntryObserver );

    67 

    68     /**

    69     * Destructor.

    70     */

    71     virtual ~CDiagPluginExecPlanImpl();

    72 

    73 public:     // New API

    74     /**

    75     * Initialize execution plan

    76     *

    77     * @param aStatus - Request status to set when plan creatation is completed.

    78     * @param aBatch - list of plug-ins to execute

    79     */

    80     void InitializeL( TRequestStatus& aStatus, 

    81                       const RPointerArray< MDiagPlugin >& aBatch );

    82 

    83     /**

    84     * Initialize execution plan from db.

    85     *   This will read current data from results database and reconstruct

    86     *   the execution plan.

    87     *

    88     *   This should be used to continue an incomplete session.

    89     *

    90     * @param aStatus - Request status to set when plan creatation is completed.

    91     */

    92     void InitializeL( TRequestStatus& aStatus );

    93 

    94     /**

    95     * Access an item in plan. 

    96     *

    97     * @param aIndex    - index 

    98     * @return Reference to plan entry at given index.

    99     */

   100     CDiagExecPlanEntryImpl& operator[]( TInt aIndex );      //lint !e1411  This is proper overload

   101 

   102     /**

   103     * Get current execution plan item.

   104     *

   105     * @return Reference to currently executing plan item.

   106     */

   107     CDiagExecPlanEntryImpl& CurrentExecutionItem();         //lint !e1411  This is proper overload

   108 

   109     /**

   110     * Reset execution cursor

   111     * 

   112     * Resets execution cursor to the beginning.

   113     */

   114     void ResetExecutionCursor();

   115 

   116     /**

   117     * Moves execution cursor to next item.

   118     *

   119     * @return ETrue if cursor is updated.

   120     *         EFalse if cursor is already at last item.

   121     */

   122     TInt MoveCursorToNext();

   123 

   124 private:     // from CActive

   125     /**

   126     * Handle Active Object completion event.

   127     * @see CActive::RunL()

   128     */

   129     virtual void RunL();

   130 

   131     /**

   132     * Cancel outstanding request

   133     * @see CActive::RunL()

   134     */

   135     virtual void DoCancel();

   136 

   137     /**

   138     * Handle errors

   139     * @see CActive::RunError()

   140     */

   141     virtual TInt RunError( TInt aError );

   142 

   143 public:     // from MDiagPluginExecPlan

   144     /**

   145     * Access an item in plan.

   146     *   @see MDiagPluginExecPlan::operator[]

   147     */

   148     virtual const MDiagExecPlanEntry& operator[]( TInt aIndex ) const;

   149 

   150     /**

   151     * Get current execution plan item.

   152     *   @see MDiagPluginExecPlan::CurrentExecutionItem

   153     */

   154     virtual const MDiagExecPlanEntry& CurrentExecutionItem() const;

   155 

   156     /**

   157     * Returns index of execution cursor. 

   158     *   @see MDiagPluginExecPlan::CurrentIndex

   159     */

   160     virtual TInt CurrentIndex() const;

   161 

   162     /**

   163     * Returns total number of items in the plan.

   164     *   @see MDiagPluginExecPlan::Count

   165     */

   166     virtual TInt Count() const;

   167 

   168     /**

   169     * Get current test index.

   170     *

   171     *   @see MDiagPluginExecPlan::CurrentTestIndex

   172     */

   173     virtual TInt CurrentTestIndex( TBool aIncludeDependency ) const;

   174 

   175     /**

   176     * Get total test count.

   177     *

   178     *   @see MDiagPluginExecPlan::TestCount

   179     */

   180     virtual TInt TestCount( TBool aIncludeDependency ) const;

   181 

   182     /**

   183     * Check if this is the last test being executed.

   184     *

   185     *   @see MDiagPluginExecPlan::IsLastTest

   186     */

   187     virtual TBool IsLastTest() const;

   188 

   189     /**

   190     * Check if this is the last plug-in being executed.

   191     *

   192     *   @see MDiagPluginExecPlan::IsLastPlugin

   193     */

   194     virtual TBool IsLastPlugin() const;

   195 

   196     /**

   197     * Returns the plug-in index that plan is resuming from.

   198     *

   199     *   @see MDiagPluginExecPlan::ResumeIndex

   200     */

   201     virtual TInt ResumeIndex() const;

   202 

   203 private: // private data types

   204     /**

   205     * State

   206     */

   207     enum TState

   208         {

   209         EStateIdle  = 0,

   210         EStateExpandDependencyAndSuites,

   211         EStateRemoveEmptySuites,

   212         EStateInsertSuiteTransitions,

   213         EStateStoreToDb,

   214         EStatePlanCreated

   215         };

   216 

   217 private: // private functions

   218     /**

   219     * C++ Constructor

   220     * @param aEngine - reference to engine.

   221     * @param aEngineConfig - reference to engine configuration information.

   222     * @param aEntryObserver - Reference to observer for each plug-in

   223     */

   224     CDiagPluginExecPlanImpl( MDiagEngineCommon& aEngine,

   225                              const TDiagEngineConfig& aEngineConfig,

   226                              MDiagExecPlanEntryImplObserver& aEntryObserver );

   227 

   228     /**

   229     * Symbian 2nd phase constructor

   230     */

   231     void ConstructL();

   232 

   233     /**

   234     * Change state

   235     *   @param aState - new state.

   236     */    

   237     void ChangeState( TState aState );

   238 

   239     /**

   240     * Plan creation phase 1. Expand dependencies

   241     *

   242     * @return ETrue if any changes are made to the plan.

   243     */

   244     TBool ExpandDependenciesL();

   245 

   246     /**

   247     * Plan creation phase 2. Expand suites to plug-ins

   248     *

   249     * @return ETrure if any changes are made to the plan

   250     */

   251     TBool ExpandSuitesL();

   252 

   253     /**

   254     * Plan creation phase 3. Remove empty suites. Delete plan entries that

   255     * just has prepare and finalize without any tests in between.

   256     *

   257     */

   258     void RemoveEmptySuites();

   259 

   260     /**

   261     * Plan creation phase 4. Insert suite transition based on parent

   262     *

   263     */

   264     void InsertSuiteTransitionsL();

   265 

   266     /**

   267     * Store next test plan item to database. Part of STEP_6.

   268     *

   269     */

   270     void StoreNextTestPluginToDbL();

   271     

   272     /**

   273     * Plan creation step 7. Prepend items from last session to new plan.

   274     */

   275     void PrependExecutedItemsL();

   276 

   277     /**

   278     * Report result to client.

   279     * 

   280     * @param aErr - Result to report back to engine. KErrNone if successful.

   281     *   

   282     */

   283     void ReportResult( TInt aErr );

   284 

   285     /**

   286     * Insert plugin

   287     *

   288     * This function will attempt to add a plugin into plan. 

   289     * If item already exists in the plan prior to the given index, it will

   290     * not add a new item. 

   291     * If item exists after the given index, and the item is a dependent item, it will

   292     * move it up in the plan, so that it will be executed earlier.

   293     * If item exists after the given index, and the item is not a dependent item, 

   294     * it will create a duplicate entry, to make sure that client specified order

   295     * is not changed.

   296     *

   297     * @param aPlugin - Plugin to insert

   298     * @param aAsDependent - whether new item is to satify dependency or not.

   299     * @param aAt - index to insert the dependent item to.

   300     * @return ETrue if plan is updated. EFalse if no changes to plan is made.

   301     */

   302     TBool InsertPluginL( MDiagPlugin& aPlugin,

   303                          TBool aAsDependent, 

   304                          TInt aAt );

   305 

   306     /**

   307     * Utility function to create a default execution plan entry

   308     *   For test plug-ins, it will create an entry with EQueueToRun as status.

   309     *   For suite plug-ins, it will create an entry with ETypeSuiteUnexpanded as type.

   310     *

   311     * @param aPlugin - Plugin to create default entry for. Either test or suite plug-in.

   312     * @param aAsDependency - Whether the entry should be created as dependency or not.

   313     *

   314     * @return New execution plan entry. Ownership is transferred.

   315     */

   316     CDiagExecPlanEntryImpl* CreateDefaultPlanEntryLC(

   317             MDiagPlugin& aPlugin,

   318             TBool aAsDependency ) const;

   319 

   320     /**

   321     * Utility function to add root suite if it does not alredy exists 

   322     * in the plan. 

   323     * 

   324     * NOTE: This should be called only from InsertSuiteTransitionsL()

   325     */

   326     void AddRootSuiteIfMissingL();

   327 

   328     /**

   329     * Utility function to push new transition into stack.

   330     *

   331     * NOTE: This should be called only from InsertSuiteTransitionsL()

   332     *

   333     * @param aStack - Stack to push new transition to.

   334     * @Param aHeadIndex - index in execution plan to head entry.

   335     */

   336     void PushNewLevelL( CStack<TTransitionStackEntry, ETrue>& aStack, TInt aHeadIndex );

   337 

   338     /**

   339     * Utility function to pop a level from stack. This will remove top entry

   340     *

   341     * NOTE: This should be called only from InsertSuiteTransitionsL()

   342     *

   343     * @param aStack - Stack to pop the head item from.

   344     */

   345     void PopLevel( CStack<TTransitionStackEntry, ETrue>& aStack );

   346 

   347     /**

   348     * Utility function to check if given level exists in stack

   349     *

   350     * NOTE: This should be called only from InsertSuiteTransitionsL()

   351     *

   352     * @param aStack - Stack to check levels in.

   353     * @param aLevelUid - Uid of leven to check in stack.

   354     * 

   355     * @return ETrue if item exists in stack. EFalse if not found.

   356     */

   357     TBool IsLevelInStack( CStack<TTransitionStackEntry, ETrue>& aStack, TUid aLevelUid ) const;

   358 

   359     /**

   360     * Utility function to check if there is more of items of the same parent

   361     * exists in the plan.

   362     *

   363     * NOTE: This should be called only from InsertSuiteTransitionsL()

   364     * 

   365     * @param aParentUid - Uid of suite to search for.

   366     * @param aIndex - Index to execution plan to start searching for.

   367     * @return ETrue if given suite is still needed.

   368     *   EFalse otherwise.

   369     */

   370     TBool IsThisSuiteNeededAfterThisIndex( TUid aSuiteUid, TInt aIndex ) const;

   371 

   372     /**

   373     * Utility function to add a SuitePrepare entry into plan.

   374     *

   375     * NOTE: This should be called only from InsertSuiteTransitionsL()

   376     *

   377     * @param aLevelUid - Uid of suite to add in plan.

   378     * @param aAt - Index in plan to add new prepare entry to.

   379     */

   380     void AddSuitePrepareL( TUid aLevelUid, TInt aAt );

   381 

   382     /**

   383     * Utility function to add a SuiteFinalize entry into plan.

   384     *

   385     * NOTE: This should be called only from InsertSuiteTransitionsL()

   386     *

   387     * @param aPrepareIndex - location in plan where prepare is at. Some information

   388     *   from prepare item will be copied to finalize.

   389     * @param aAt - Index in execution plan to add finalize entry to.

   390     */

   391     void AddSuiteFinalizeL( TInt aPrepareIndex, TInt aAt );

   392     

   393     /**

   394     * Log plan information to debug log. This function does nothing in release build.

   395     */

   396     void LogPlanL() const;

   397 

   398     /**

   399     * Debug function that validate that entries are written to db correctly.

   400     * This function does nothing in release build.

   401     */

   402     void LogPlanInRecordL() const;

   403 

   404 private: // data

   405 

   406     /**

   407     * iPlan - holds plan entries

   408     * Individual entries are owned by the array.

   409     */

   410     RPointerArray<CDiagExecPlanEntryImpl> iPlan;

   411 

   412     /**

   413     * iExecutedEntries  - Items that are already executed in the

   414     * previous session.

   415     * Individual entries are owned by the array.

   416     */

   417     RPointerArray<CDiagExecPlanEntryImpl> iExecutedEntries;

   418 

   419     /**

   420     * iExecutionCursor - currently executing item.

   421     */

   422     TInt iExecutionCursor;

   423 

   424     /**

   425     * iResumeIndex - Index which session is being resumed from.

   426     */

   427     TInt iResumeIndex;

   428 

   429     /**

   430     * iEngine - Reference to diag engine.

   431     */

   432     MDiagEngineCommon& iEngine;

   433 

   434     /**

   435     * iEngineConfig - Enine configuration information.

   436     */

   437     const TDiagEngineConfig& iEngineConfig;

   438 

   439     /**

   440     * iPlanEntryObserver - Plan entry observer. Passed to each plan entry

   441     *    when it is created.

   442     */

   443     MDiagExecPlanEntryImplObserver& iPlanEntryObserver;

   444 

   445     /**

   446     * iClientStatus - TRequestStatus of the client. Used to notify

   447     * completion and error.

   448     * Ownership - Does not own.

   449     */

   450     TRequestStatus* iClientStatus;

   451 

   452     /**

   453     * iState - state of the execution plan creation.

   454     *   @see TState

   455     */

   456     TState iState;

   457     };

   458 

   459 #endif // DIAGPLUGINEXECPLANIMPL_H

   460 

   461 

   462 // End of File

   463