DOCS-251: legacy document migration

Author: Sam Kleinman

draft/tutorial/expire-least-recently-used-data-session-objects.txt

@@ -0,0 +1,140 @@
+.. default-domain:: mongodb
+:title: MongoDB Use Cases - Session Objects
+
+.. http://www.mongodb.org/display/DOCS/Use+Case+-+Session+Objects
+
+===============
+Session Objects
+===============
+
+
+MongoDB is a good tool for storing HTTP session objects.
+
+One implementation model is to have a sessions collection, and store the
+session object's \_id value in a browser cookie.
+
+With its update-in-place design and general optimization to make updates
+fast, MongoDB is efficient at receiving an update to the session
+object on every single app server page view.
+
+Purging Old Sessions using TTL Collections
+------------------------------------------
+
+The best method to manage and purge old sessions is to use a
+:term:`TTL Collection <mongodb:ttl-collections>`.  
+A TTL collection is a MongoDB collection which has an ``expireAfterSeconds``
+index on an :term:`ISODate <mongodb:isodate>` field.
+
+For example, create a collection :samp:`sessions` with three fields:
+
+   :samp:`_id`
+   
+      Automatically created by MongoDB
+      
+   :samp:`lastUsed`
+   
+      An ISODate field which you will update every time an action occurs
+      in the session.
+      
+   :samp:`sessionId`
+   
+      An identifier for the session.  This could be an ObjectId from 
+      another collection for example.
+      
+.. code-block:: javascript
+
+   > db.createCollection('sessions');
+   {"ok": 1}
+   
+   > var record = { lastUsed: ISODate(), sessionId: "1cf41e17e21d5697ac7ed84d10caa456"}
+   > db.sessions.insert(record)
+   > db.sessions.find().pretty()
+   {
+           "_id" : ObjectId("50fee58e95fa0c941f134114"),
+           "lastUsed" : ISODate("2013-01-22T19:16:23.570Z"),
+           "sessionId" : "1cf41e17e21d5697ac7ed84d10caa456"
+   }
+      
+You now have a collection with one record.  Now create the TTL index on the 
+collection:
+
+.. code-block:: javascript
+
+   > db.sessions.ensureIndex({lastUsed:1}, {expireAfterSeconds:300})
+   
+This creates a TTL index on the :samp:`lastUsed` field.
+Any document whose :samp:`lastUsed` field has a time older than five
+minutes (300 seconds) will be purged.  
+
+.. code-block:: javascript
+
+   > db.sessions.getIndexes()
+   [
+        {
+            "v" : 1,
+            "key" : {
+                "_id" : 1
+            },
+            "ns" : "writing.sessions",
+            "name" : "_id_"
+        },
+        {
+            "v" : 1,
+            "key" : {
+                "lastUsed" : 1
+            },
+            "ns" : "writing.sessions",
+            "name" : "lastUsed_1",
+            "expireAfterSeconds" : 300
+        }
+    ]
+
+And if we wait a few minutes that solitary document will be purged:
+
+.. code-block:: javascript
+
+    > db.sessions.find()
+    >
+    
+.. note::
+
+   If you insert a document whose timestamp is already ``older`` than
+   the expiration window set in :samp:`expireAfterSeconds`, MongoDB 
+   will insert the document and then purge it at the next run of the
+   TTL scavenger process.
+
+
+Aging Out Old Sessions using Capped Collections
+-----------------------------------------------
+
+One method to age out old sessions is to use the auto-LRU facility of
+:term:`capped collections <mongodb:capped collections>`.
+A complication is that objects in capped collections may not grow beyond
+their initial allocation size.
+To handle this, we can "pre-pad" the objects to some maximum size on
+initial addition, and then on further updates we are fine if we do not
+go above the limit. The following MongoDB shell JavaScript example
+demonstrates padding:
+
+.. code-block:: javascript
+
+	> db.createCollection('sessions', { capped: true, size : 1000000 } )
+	{"ok" : 1}
+	> p = "";
+	> for( x = 0; x < 100; x++ ) p += 'x';
+	> s1 = { info: 'example', _padding : p };
+	{"info" : "example" , "_padding" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
+	> db.sessions.save(s1)
+	> s1
+	{"info" : "example" , "_padding" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" , "_id" :  ObjectId( "4aafb74a5761d147677233b0") }
+
+	> // when updating later
+	> s1 = db.sessions.find( { _id : ObjectId( "4aafb74a5761d147677233b0") } )
+	{"_id" :  ObjectId( "4aafb74a5761d147677233b0")  , "info" : "example" , "_padding" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
+	> delete s._padding;
+	true
+	>  s.x = 3; // add a new field
+	3
+	> db.sessions.save(s);
+	> s
+	{"_id" :  ObjectId( "4aafb5a25761d147677233af")  , "info" : "example" , "x" : 3}