The following examples show how to use cflock blocks in a variety of situations.
Example with application, server, and session variables
This example shows how you can use cflock to guarantee the consistency of data updates to variables in the Application, Server, and Session scopes.
This example does not handle exceptions that arise if a lock times out. As a result, users see the default exception error page on lock time-outs.
The following sample code might be part of the Application.cfm file:
<cfapplication name="ETurtle" sessiontimeout=#createtimespan(0,1,30,0)# sessionmanagement="yes"> <!--- Initialize the Session and Application variables that will be used by E-Turtleneck. Use the Session lock scope for the session variables. ---> <cflock scope="Session" timeout="10" type ="Exclusive"> <cfif not IsDefined("session.size")> <cfset session.size = ""> </cfif> <cfif not IsDefined("session.color")> <cfset session.color = ""> </cfif> </cflock> <!--- Use the Application scope lock for the Application.number variable. This variable keeps track of the total number of turtlenecks sold. The following code implements the scheme shown in the Locking Application variables effectively section ---> <cfset app_is_initialized = "no"> <cflock scope="Application" type="readonly"> <cfset app_is_initialized = IsDefined("Application.initialized")> </cflock> <cfif not app_is_initialized > <cflock scope="application" timeout="10" type="exclusive"> <cfif not IsDefined("Application.initialized") > <cfset Application.number = 1> <cfset Application.initialized = "yes"> </cfif> </cflock> </cfif> <!--- Always display the number of turtlenecks sold ---> <cflock scope="Application" timeout="10" type ="ReadOnly"> <cfoutput> E-Turtleneck is proud to say that we have sold #Application.number# turtlenecks to date. </cfoutput> </cflock>
The remaining sample code could appear inside the application page where customers place orders:
<html> <head> <title>cflock Example</title> </head> <body> <h3>cflock Example</h3> <cfif IsDefined("Form.submit")> <!--- Lock session variables ---> <!--- Note that we use the automatically generated Session ID as the order ID ---> <cflock scope="Session" timeout="10" type="ReadOnly"> <cfoutput>Thank you for shopping E-Turtleneck. Today you have chosen a turtleneck in size <b>#form.size#</b> and in the color <b>#form.color#</b>. Your order ID is #Session.sessionID#. </cfoutput> </cflock> <!--- Lock session variables to assign form values to them. ---> <cflock scope="Session" timeout="10" type="Exclusive"> <cfparam name=Session.size default=#form.size#> <cfparam name=Session.color default=#form.color#> </cflock> < !--- Lock the Application scope variable application.number to update the total number of turtlenecks sold. ---> <cflock scope="Application" timeout="30" type="Exclusive"> <cfset application.number=application.number + 1> </cflock> <!--- Show the form only if it has not been submitted. ---> <cfelse> <form action="cflock.cfm" method="Post"> <p> Congratulations! You have just selected the longest-wearing, most comfortable turtleneck in the world. Please indicate the color and size you want to buy.</p> <table cellspacing="2" cellpadding="2" border="0"> <tr> <td>Select a color.</td> <td><select type="Text" name="color"> <option>red <option>white <option>blue <option>turquoise <option>black <option>forest green </select> </td> </tr> <tr> <td>Select a size.</td> <td><select type="Text" name="size"> <option>small <option>medium <option>large <option>xlarge </select> </td> </tr> <tr> <td></td> <td><input type="Submit" name="submit" value="Submit"> </td> </tr> </table> </form> </cfif> </body> </html>
In this simple example, the Application.cfm page displays the Application.number variable value. Because the Application.cfm file is processed before any code on each ColdFusion page, the number that displays after you click the submit button does not include the new order. One way you can resolve this problem is by using the OnRequestEnd.cfm page to display the value at the bottom of each page in the application.
Example of synchronizing access to a file system
The following example shows how to use a cflock block to synchronize access to a file system. The cflock tag protects a cffile tag from attempting to append data to a file already open for writing by the same tag executing on another request.
If an append operation takes more than 30 seconds, a request waiting to obtain an exclusive lock to this code might time out. Also, this example uses a dynamic value for the name attribute so that a different lock controls access to each file. As a result, locking access to one file does not delay access to any other file.
<cflock name=#filename# timeout=30 type="Exclusive"> <cffile action="Append" file=#fileName# output=#textToAppend#> </cflock>
Example of protecting ColdFusion extensions
The following example shows how you can build a custom tag wrapper around a CFX tag that is not thread-safe. The wrapper forwards attributes to the non-thread-safe CFX tag that is used inside a cflock tag.
<cfparam name="Attributes.AttributeOne" default=""> <cfparam name="Attributes.AttributeTwo" default=""> <cfparam name="Attributes.AttributeThree" default=""> <cflock timeout=5 type="Exclusive" name="cfx_not_thread_safe"> <cfx_not_thread_safe attributeone=#attributes.attributeone# attributetwo=#attributes.attributetwo# attributethree=#attributes.attributethree#> </cflock>