--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mpx/collectionframework/collectionengine/inc/mpxcollectioncache.h	Thu Dec 17 08:55:47 2009 +0200
@@ -0,0 +1,184 @@
+/*
+* 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
+