/*
* Copyright (c) 2007 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:  Generic collection cache
*
*/


#ifndef MPXCOLLECTIONCACHE_H
#define MPXCOLLECTIONCACHE_H

// INCLUDES
#include <e32std.h>
#include <e32base.h>
#include <mpxitemid.h>

// CLASS FORWARDS
class CMPXMedia;
class CMPXCollectionPath;
class TMPXAttribute;
class CMPXCollectionCacheNode;

/**
*  The collection cache stores information already retrieved by clients so it can be
*  returned immediately if requested again. The information is stored in a tree
*  structure, where each tree node corresponds to a path node. When information is
*  requested, the path is mapped against the tree and if a corresponding node exists the
*  results are returned from cache.
*
*  The cache can be limited in size, if the client defines a maximum size, lower priority
*  nodes are discarded to make room for new information. The criteria considered when
*  discarding nodes include: priority value (specified by the client), path level and
*  time of addition.
*
*  @lib mpxcollectionengine.lib (not exported)
*/
NONSHARABLE_CLASS(CMPXCollectionCache) :
    public CBase
    {
public:
    /**
    *  Two-phased constructor.
    *  @param aMaximumSizeRatio maximum cache size in percentage ratio
    *         If not specified the cache does not have a limit
    *  @return Constructed object
    */
    static CMPXCollectionCache* NewL(TInt aMaximumSizeRatio = -1);

    /**
    *  Destructor
    */
    virtual ~CMPXCollectionCache();

public:
    /**
    *  Cache entry priority values. Entries with lower priority will be discarded
    *  sooner than the ones with higher priority.
    */
    enum TCachePriority
        {
        EPriorityLow,
        EPriorityNormal,
        EPriorityHigh
        };

public:
    /**
    *  Adds a result set to the cache.
    *  @param aPath path defining the context of the results.
    *  @param aAttrs attributes requested by the client application and included in
    *         the result set.
    *  @param aResults result set corresponding to the path.  Not owned.
    *  @param aNotCacheableAttrs attributes that are not cacheable
    *  @param aMediaFromOpenL whether or not this media was from an OpenL
    *  @param aPriority result set priority
    *  @return CMPXMedia object in the cache or the original object if add failed
    */
    CMPXMedia* AddL(
        const CMPXCollectionPath& aPath, 
        const TArray<TMPXAttribute>& aAttrs,
        CMPXMedia& aResults, 
        TBool aMediaFromOpenL = EFalse,
        TCachePriority aPriority = EPriorityNormal );

    /**
    *  Returns the information corresponding to the specified path and attribute set
    *  if available in the cache.
    *  @param aPath path defining the information context.
    *  @param aAttrs attribute set requested by the client.
    *  @return Valid results or NULL if the path/attribute set specified cannot be
    *          found in the cache.
    */
    CMPXMedia* GetL(
        const CMPXCollectionPath& aPath,
        const TArray<TMPXAttribute>& aAttrs,
        TBool aMediaFromOpenL = EFalse );

    /**
    *  Removes the specified path and all its children from the cache.
    *  @param aPath path defining the context to be removed.
    */
    void RemoveL(const CMPXCollectionPath& aPath);

    /**
    * Resets cache and removes all nodes
    */
    void Reset();

    /**
    * Handle some change from the collection
    * @param aCollectionId collectoin that the change is comming from
    * @param aChangeItemId item ID of the changed event
    */
    void HandleChangeL( TUid aCollectionId, TMPXItemId aChangeItemId );
    
private:

    /**
    *  C++ constructor
    *  @param aMaximumSizeKb maximum cache size in percentage ratio.
    */
    CMPXCollectionCache(TInt aMaximumSizeRatio);

    /**
    *  2nd phase contructor
    */
    void ConstructL();

    /**
    *  Returns the cache node corresponding to the specified path.
    *  @param aPath path to be looked up in the cache.
    *  @param aCreateNodes if ETrue all the missing nodes for the specified
    *         path will be created if they do not already exist. If EFalse
    *         the method returns NULL if corresponding node is not found.
    *  @return valid cache node if found or created, NULL if not found.
    */
    CMPXCollectionCacheNode* NodeFromPathL(const CMPXCollectionPath& aPath,
        TBool aCreateNodes = EFalse);
        
    /**
    *  Removes a specified node and all its children from the cache.
    *  @param aNode node to be removed.  Ownership is transferred.
    */
    void RemoveNode(CMPXCollectionCacheNode* aNode);
    
    /**
    *  Checks the memory condition and clears cache to free some memory
    *  maximum percentage ratio specified in the constructor is used to detect
    *  low memory condition
    *  @return EFalse if low memory condition detected, ETrue otherwise 
    */
    TBool ManageCacheSizeL();

#ifdef _DEBUG
    /**
    *  Prints the cache tree.
    */
    void PrintTree( TBool aPrintAtts = EFalse );
#endif
    
private:
    /**
    *  Root node for the cache tree, created when the cache is created.
    */
    CMPXCollectionCacheNode* iRoot;

    /**
    *  Maximum size of the cache in percentage ratio, specified by the client.
    */
    TInt iMaximumSizeRatio;
    };

#endif // MPXCOLLECTIONCACHE_H