[cvs] expresso commit by lhamel: isMutable, cache access

[JCorporate Ltd]

Log Message:
-----------
isMutable, cache access

Modified Files:
--------------
    expresso/expresso-web/expresso/doc/edg:
        caching.xml

Revision Data
-------------
Index: caching.xml
===================================================================
RCS file: /home/javacorp/.cvs/expresso/expresso/expresso-web/expresso/doc/edg/caching.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -Lexpresso-web/expresso/doc/edg/caching.xml -Lexpresso-web/expresso/doc/edg/caching.xml -u -r1.7 -r1.8
--- expresso-web/expresso/doc/edg/caching.xml
+++ expresso-web/expresso/doc/edg/caching.xml
@@ -87,6 +87,34 @@
 also be cached, and you can control the number of cache entries for each
 object, using more caching for items more frequently used by your application.
 		</para>
+        <para>
+                    Previous to version 5.6.1, the Expresso caching system
+                    offered no easy access to the actual cached items. Instead, when a
+                    DBObject was retrieved, and a cache hit was found, a copy of the cached item
+                    was automatically returned. This is very appropriate for a multi-threaded application
+                    and situations where the retrieved items may be modified.
+                    However, there are many read-only situations in code
+                    where the retrieved item is not
+                    intended for modification. In these cases, especially within loops,
+                    creating a new copy of the cached object is expensive.
+                    To provide access to the cache where a copy is not made, a new attribute
+                    DBObject.isMutable() is now set on cached copies. This attribute is now
+                tested during any set* and update() methods, throwing an exception if the DBObject
+ is marked as immutable. This protects usage of the actual cached items as a read-only source.
+                To provide access to the actual cached, read-only objects, two new methods
+                (one static and one instance method) are available in DBObject:
+            <programlisting>
+                    public DBObject getImmutableObjectFromCache(String keyValues)
+                    public static DBObject getImmutableCachedObject(Class dbobjClass, String keyValues)
+            </programlisting>
+        </para>
+        <para>
+            An example of access might be:
+            <programlisting>
+            Room room = (Room) DBObject.getImmutableCachedObject(Room.class, roomID);
+            </programlisting>
+        </para>
+
 		<para>
 The cache manager also performs automatic memory management by keeping
 a monitor of the amount of memory available and used, and automatically