/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/**

 * @note This class is provided only if module test hooks are set on.

 */

#include "alfmoduletestconf.h"

#ifdef USE_MODULE_TEST_HOOKS_FOR_ALF

#ifndef ALFMODULETESTMAP_H

#define ALFMODULETESTMAP_H

#include <e32def.h> 

#include "alfmoduletestitem.h"

#include "alfmoduletesttype.h"

/**

 * Class CAlfModuleTestMap

 * 

 * Provides map functionality for the key-value-pairs.

 * In test cases, this should most likely be used so, that 

 * first test case classes create items with certain keys, for example with handle values.

 * Then, define hooks are used in the code to update values that corresond the correct handles.

 * In the end, test case classes can check that items have correct values set and if the test

 * is passed.

 * 

 * @note When this item is copied, also the contents of the map item array are copied

 *       into new map item array. In other words, copy can be thought as deep copy

 *       instead of just shallow copy of array pointer.

 *       

 * @see CAlfModuleTestItem

 */

template< class T >

NONSHARABLE_CLASS( TAlfModuleTestMap )

    {

public:

    // Maximum item count in the map

    static const TInt KMaxArrayCount = 100;

    // Maximum accepted test type count in the map

    static const TInt KMaxAcceptArrayCount = 20;

    /**

     * Constructor to initialize variables.

     */

    TAlfModuleTestMap():

        iArrayCount( 0 )

        {

        }

    /**

     * @note This will return normal items and also items that are links.

     * 

     * @param aTestType Informs what type of test is accepted. Others are skipped.

     * @param aKey Key of the map item.

     * @return T* Ownership is not transferred.

     *            NULL if item is not found.

     */

    TAlfModuleTestItem< T >* Find( const TAlfModuleTestType& aTestType, TInt aKey )

        {

        // Try to find the item corresponding the given key.

        for ( TInt i = 0; i < iArrayCount; ++i )

            {

            TAlfModuleTestItem< T >& testItem( iArray[ i ] );

            if ( testItem.Key() == aKey

                 && testItem.TestTypeMatch( aTestType ) )

                {

                return &( testItem );

                }

            }

        // Item corresponding the given key was not found.

        return NULL;

        }    

    /**

     * Finds the actual item.

     * 

     * @note If the given key identifies a link item, 

     *       then search is continued to the actual item

     *       through the link chain.

     *       Link item is not returned here.

     * 

     * @param aTestType Test type of the linked item and link item.

     * @param aKey Key of the item. This can also be a key to a link item.

     * @return TAlfModuleTestItem< T >* Actual item. 

     *                                  NULL if item was not found.

     *                                  Ownership is not transferred.

     */

    TAlfModuleTestItem< T >* FindActual( const TAlfModuleTestType& aTestType, TInt aKey )

        {

        TAlfModuleTestItem< T >* item( Find( aTestType, aKey ) );

        while ( item && item->LinkTargetKey() != KErrNotFound )

            {

            // Item is link.

            // So, find the actual item through link targets.

            item = Find( aTestType, item->LinkTargetKey() );

            }

        return item;

        }

    /**

     * Function to append new item into the map.

     * 

     * @param aTestType Describes for what case the appended test item is created for.

     * @param aKey Key of the map item.

     * @param aDefaultValue Default value for the map item.

     * @return TInt System wide error code.

     */    

    TInt Append( const TAlfModuleTestType& aTestType, TInt aKey, const T& aDefaultValue )

        {

        if ( !Accept( aTestType ) )

            {

            // Given test type has not been set as accepted.

            return KErrNotSupported;

            }

        else if ( Find( aTestType, aKey ) )

            {

            // Item already exists in the map.

            return KErrAlreadyExists;

            }        

        else if ( iArrayCount == KMaxArrayCount )

            {

            // Array already full.

            return KErrOverflow;

            }

        // Append new item into the array.

        iArray[ iArrayCount ] = TAlfModuleTestItem< T >( aTestType, aKey, aDefaultValue );

        ++iArrayCount;

        return KErrNone;        

        }

    /**

     * Creates and appends link item that links to another item.

     * 

     * @param aTestType Test type of the linked item and link item.

     * @param aLinkKey Link item key.

     * @param aTargetKey Target item key.

     * @return TInt System wide error code.

     */

    TInt AppendLink( const TAlfModuleTestType& aTestType, TInt aLinkKey, TInt aTargetKey )

        {

        if ( !Accept( aTestType ) )

            {

            // Given test type has not been set as accepted.

            return KErrNotSupported;

            }

        else if ( Find( aTestType, aLinkKey ) )

            {

            // Link item already exists in the map.

            return KErrAlreadyExists;

            }

        else if ( !FindActual( aTestType, aTargetKey ) )

            {

            // Link has to point to another existing item.

            // Also, link has to point to the chain that ends to actual item.

            // Then, links will not create forever loops. Loops could occur

            // if links in chain point to each other creating loops.

            return KErrNotFound;

            }

        else if ( iArrayCount == KMaxArrayCount )

            {

            // Array already full.

            return KErrOverflow;

            }

        // Create link item because original item exists and link chain is correct.

        // Append new link item into the array and link it to another link or to

        // actual item.

        TAlfModuleTestItem< T >* target( Find( aTestType, aTargetKey ) );

        // Set value of the link same as its target's value.

        iArray[ iArrayCount ] = TAlfModuleTestItem< T >( aTestType, aLinkKey, target->Value() );

        iArray[ iArrayCount ].SetLinkTargetKey( target->Key() );

        ++iArrayCount;

        return KErrNone;            

        }

    /**

     * Sets the value for the actual item.

     * Item itself should already appended into map and exist

     * in the array before setting its value here.

     * 

     * @note Some items may be links. But, only the value of the

     *       actual item in the end of the link chain is set here.

     * 

     * @param aTestType Describes for what case the item is for.

     * @param aKey Key of the map item.

     * @param aValue Value for the map item.

     * @return TInt System wide error code.

     */

    TInt SetActualValue( const TAlfModuleTestType& aTestType, TInt aKey, const T& aValue )

        {

        TAlfModuleTestItem< T >* item( FindActual( aTestType, aKey ) );

        if ( !item )

            {

            // Actual item was not found from the array.        

            return KErrNotFound;            

            }

        // Actual item exists and it is not link item. So, set its values.

        item->SetValue( aValue );        

        return KErrNone;

        }

    /**

     * Find an actual item if it exists and gets its value if item is found

     * and value has been set.

     * 

     * @param aTestType Describes for what case the item is for.

     * @param aKey Key of the map item.

     * @param aValue If map item is found, value of the item is set here.

     * @param aAcceptDefault ETrue if an existing object having its default value

     *                       is accepted. EFalse if value should have been updated

     *                       separately.

     * @return TBool ETrue if map item is found and value has been set. Else EFalse. 

     */    

    TBool GetActualValue( 

        const TAlfModuleTestType& aTestType, TInt aKey, T& aValue, TBool aAcceptDefault )

        {

        const TAlfModuleTestItem< T >* item( FindActual( aTestType, aKey ) );

        if ( item && ( aAcceptDefault || item->ValueSetCount() > 0 ) )

            {

            aValue = item->Value();

            return ETrue;

            }

        return EFalse;

        }

    /**

     * Finds an actual item if it exists and checks if it equals the given value.

     * 

     * @param aTestType Describes for what case the item is for.

     * @param aKey Key of the map item.

     * @param aValue Value of the map item.

     * @return TBool ETrue if item is found and its value equals given value. Else EFalse. 

     */

    TBool ActualEquals( const TAlfModuleTestType& aTestType, TInt aKey, const T& aValue )

        {

        T value( aValue );

        if ( GetActualValue( aTestType, aKey, value, ETrue ) && value == aValue )

            {

            return ETrue;

            }

        return EFalse;

        }

    /**

     * @return TInt Number of map items

     */

    TInt ItemCount() const

        {

        return iArrayCount;

        }

    /**

     * @return const TAlfModuleTestItem< T >& Reference to the map item

     */

    const TAlfModuleTestItem< T >& Item( TInt aIndex ) const

        {

        return iArray[ aIndex ];

        }

    /**

     * Appends an accepted test type into the accepted array.

     * 

     * @note Only items of accepted test type can be appended

     *       into this map.

     * 

     * @param aTestType Test item type that is accepted for this map.

     * @return TInt System wide error code.

     */

    TInt AppendAccept( const TAlfModuleTestType& aTestType )

        {

        if ( Accept( aTestType ) )

            {

            // Type already exists in the array.

            return KErrAlreadyExists;

            }

        else if ( iAcceptArrayCount == KMaxAcceptArrayCount )

            {

            // Array already full.

            return KErrOverflow;

            }

        iAcceptArray[ iAcceptArrayCount ] = aTestType;

        ++iAcceptArrayCount;

        return KErrNone;

        }

    /**

     * @param aTestType Test item type to be checked.

     * @return TBool ETrue if given test type is set as accepted for this map.

     *               Else EFalse.

     */

    TBool Accept( const TAlfModuleTestType& aTestType ) const

        {

        for ( TInt i = 0; i < iAcceptArrayCount; ++i )

            {

            if ( aTestType == iAcceptArray[ i ] )

                {

                return ETrue;

                }

            }

        return EFalse;

        }

    /**

     * Resets all the array items that match the given test type

     * to given default value.

     * 

     * @param aTestType The test type of items that should be resetted.

     * @param aValue Reference to the value that items are resetted to.

     */

    void ResetItems( const TAlfModuleTestType& aTestType, const T& aDefaultValue )

        {

        for ( TInt i = 0; i < iArrayCount; ++i )

            {

            if ( iArray[ i ].TestTypeMatch( aTestType ) )

                {

                iArray[ i ].Reset( aDefaultValue );

                }

            }

        }

    /**

     * Resets the map

     */

    void Reset()

        {

        // Just reset the counter.

        // We do not bother to reset map items, because when counter is reseted

        // already set items and their info is left out of the scope.

        iArrayCount = 0;

        iAcceptArrayCount = 0;

        }

private: // data

    TAlfModuleTestItem< T > iArray[ KMaxArrayCount ];

    TInt iArrayCount;

    TAlfModuleTestType iAcceptArray[ KMaxAcceptArrayCount ];

    TInt iAcceptArrayCount;

    };

#endif // ALFMODULETESTMAP_H

#endif // USE_MODULE_TEST_HOOKS_FOR_ALF

// End of File