-----------------------------------------------------
RSESSION - Session Management for Clusters That 
		   Support Failover with Allaire Cold Fusion
-----------------------------------------------------

--------------------------------------
How to Install and Convert to RSESSION
--------------------------------------

You should be able to convert your application very easily:

0) Go into Application.cfm and make three changes.  First, set request.dsn
equal to the name of your datasource.  Second and Third, change 
".backslap.com" in the DOMAIN="" parameter of CFCOOKIE to be your domain. 
This will insure cookies set by a server are readable across all nodes of
your cluster.  THIS IS IMPORTANT.

1) Now, make a database table using the provided DDL (see tblLookupSession.sql 
for script).  These are for Sybase but your DB platform should be very similar.

CREATE TABLE dbo.tblLookupSession 
(
    CFID             int      NOT NULL,
    CFTOKEN          char(35) NOT NULL,
    dtLastHit        datetime DEFAULT GETDATE() NOT NULL,
    iHitCount        int      DEFAULT 0 NOT NULL,
    txtSessionPacket text     NULL
)
go

2) Create the primary key:

CREATE UNIQUE NONCLUSTERED INDEX XPKtblLookupSession
    ON dbo.tblLookupSession(CFID ASC,CFTOKEN)
go

3) Make a subdirectory from your root directory named "rsession", all lower 
   case for Unix.
4) Dump the session_*.cfm tags into that subdirectory.
5) Run a search and replace on your application:
	Search for "session."
	Replace with "request.session."
	
	That should find both references like <cfif session.foo> as well as
	<cfoutput>#session.bar#</cfoutput>

6) schedule a recurring task every 1 minute to run /rsession/session_clean.cfm 
in scheduler (or using cron/at to run the process from a browser outside of 
the uber-reliable CFSCHEDULER). This will hose any session older than 20 minutes.  
This is also where you have access to the holy grail of state management: 
OnSessionEnd().   Add code as necessary.  I have provided session_clean_example.cfm 
as a sample of what we are using the template for.  Real-world examples always 
seem to illustrate the point for me.

7) Run a search and replace on <cflock ...> and remove it. 
8) Remove the CFAPPLICATION tag from your Application.cfm (unless you still use 
   the Application scope)
9) Sit back, add machines to your cluster until your rack is full.
10) Laugh at people still using CFLOCK.  :)



-------------------------------------
How to Install the Custom Tag Version
-------------------------------------

In this version of RSESSION, we have added a Custom Tag version that
allows larger installations to simplify code maintenance for large bases
of developers.  This version requires just two lines of code - one in
Application.cfm and one in OnRequestEnd.cfm as well as the declaration of
a DSN variable.  Check the /customtags/ subdirectory of this distribution
for information and read the CHANGELOG.

Directions:

1. Follow steps 1 and 2 above.
2. Copy /customtags/session_*.cfm source files to
   /opt/coldfusion/CustomTags or c:\cfusion\CustomTags instead of a
   subdirectory in your project.  Aaron Smith <aaron.smith@albertsons.com> 
   suggests putting them in c:\cfusion\CustomTags\rsession or 
   /opt/coldfusion/CustomTags/rsession for cleanliness.
3. Create a DSN called "rsession", OR, modify the line:
   <cfset request.dsn = "rsession">
   in the file session_check.cfm on line 11.
4. Insert the command <cf_session_check> into your Application.cfm and
   the command <cf_session_save> into your OnRequestEnd.cfm.
5. Follow steps 5-9 above.
6. Your scheduled task will need to execute <cf_session_clean> from a template
   inside your document tree.
6. Follow step 10 multiple times.