This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
All rights reserved. No part of this book shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from the publisher. No patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions. Nor is any liability assumed for damages resulting from the use of the information contained herein.
Development Editor Damon Jordan
International Standard Book Number: 0-672-32462-8
Indexer Erika Millen
Library of Congress Catalog Card Number: 2002110482 Printed in the United States of America First Printing: April 2003 04 03 02 01
4
3 2 1
Trademarks All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Sams Publishing cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.
Warning and Disclaimer Every effort has been made to make this book as complete and as accurate as possible, but no warranty or fitness is implied.The information provided is on an “as is” basis.The author and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book or from the use of the CD or programs accompanying it.
Managing Editor Charlotte Clapp Project Editor Andy Beaster Copy Editor Kezia Endsley
Proofreader Suzanne Thomas Technical Editors Peter Reese Chris Hiester Team Coordinator Vanessa Evans Media Developer Dan Scherf Designer Gary Adair
❖ To my family, friends, and teachers:Thanks for everything. —Pete Freitag To my family and loved ones:Thank you so much for your on-going support. —Brad Leupen To my family and friends:Thanks for your support. —Chris Reeves ❖
Contents at a Glance Introduction 1 I Datatypes and Containers 1 String Manipulation 7 2 Working with Lists 23 3 Arrays 37 4 Structures 51 5 Queries 67 6 Dates and Times 79 II Controlling Application Flow 7 Application Flow 91 8 Exception Handling 101 III Using Utility Tags 9 Charting Data 113 10 Files and Directories 125 11 Using Internet Protocols 137 12 Using Verity 151 13 User Authentication 159
IV Database Integration 14 Structured Query Language (SQL) 181 15 Stored Procedures 203 V Language Extensibility Features 16 User Defined Functions 217 17 ColdFusion Custom Tags 229 18 CFX API Custom Tags 239 19 Components 259 20 Objects 271 21 WDDX 281 22 XML 295 23 Web Services 305 24 J2EE Interoperability 317 VI Appendixes A Online ColdFusion Resources 329 B Security 333 C Migrating from ColdFusion 5 to CFMX 339 D Converting Between Tags and Scripting 341 Index 349
viii
Contents
Table of Contents Table of Contents Introduction
1
How This Book Is Organized 1 How to Use This Book 1 Chapter Overviews 2
Introduction 7 Concatenating Strings 7 Delimiting Strings 8 Using ASCII Character Codes 9 Forming Substring 10 Encrypting Strings 12 Hashing Strings 13 Iterating Through a String 14 Reading a File Line by Line 15 Searching a String 16 Replacing Substrings within a String 17 Using REFind() to Perform a Literal String Search 18 Using Qualifiers to Indicate Multiplicity 19 Using Wildcards 20 Using Brackets 20 Performing OR Operations 21 Escaping Special Characters 21 Using Character Classes 22
Contents
2 Working with Lists 23 2.0. 2.1. 2.2. 2.3. 2.4. 2.5. 2.6. 2.7. 2.8. 2.9. 2.10. 2.11. 2.12.
Introduction 23 Creating Lists 23 Changing Delimiters 24 Extracting Elements 25 Handling Empty Values 26 Changing Values in a List 28 Searching a List 29 Sorting a List 30 Adding Qualifiers to a List 30 Looping Through a List 31 Looping Over a Structure’s Key List 32 Looping Until a List Is Empty 33 Parsing Input Forms 34
Introduction 37 Creating an Array 37 Adding an Element to an Array 38 Displaying a Value in an Array 39 Looping over an Array 40 Manipulating Array Values 41 Sorting an Array 41 Multidimensional Arrays 44 Creating Arrays with More Than Three Dimensions 45 Array Aggregate Functions 46 Array Utility Functions 47 Array Information Functions 48
4 Structures 51 4.0. 4.1. 4.2. 4.3.
Introduction 51 Creating a Structure 52 Using Structure Information Functions 52 Using Structure Management Functions 53
ix
x
Contents
4.4. 4.5. 4.6. 4.7. 4.8. 4.9. 4.10. 4.11.
Inserting Values into a Structure 55 Updating Values in a Structure 56 Displaying the Value of an Element in a Structure Using the Key Name 57 Using Dot Notation 58 Looping Over a Structure 59 Using Structure Utility Functions 60 Copying Structures 61 Sorting Structures 63
Introduction 67 Querying a Database 67 Programmatically Creating Queries 69 Displaying Query Results 70 Using Query Variables 71 Creating Queries of Queries 73 Converting a Query Column to a List 75 Caching a Query 76
6 Dates and Times 79 6.0. 6.1. 6.2. 6.3. 6.4. 6.5. 6.6. 6.7. 6.8.
Introduction 79 Creating a Date,Time, or DateTime Object 79 Formatting Dates 80 Comparing Dates 82 Determining Date Differences 83 Formatting Times 84 Defining Time Spans 85 Using Date Information Functions 86 Managing Dates and Times in Different Locales 88
Introduction 91 Creating a ColdFusion Application 91 Using the Application Variable Scope 94 Implementing Session Management 95 Implementing Client Management 96 Storing Client State Using the Registry 97 Storing Client State Using Cookies 98 Storing Client State Using a Database 99
III Using Utility Tags 9 Charting Data 113 9.0. 9.1. 9.2. 9.3. 9.4. 9.5. 9.6. 9.7.
Introduction 113 Creating a Simple Chart 113 Managing the Chart Container 114 Managing Chart Series 117 Populating a Chart Series with Explicit Values 121 Populating Charts with Query Values 121 Implementing Click-Through Behaviors in Charts 122 Administering Charts Through the ColdFusion Administrator 123
11 Using Internet Protocols 137 11.0. 11.1. 11.2. 11.3. 11.4. 11.5. 11.6. 11.7. 11.8. 11.9. 11.10. 11.11.
Introduction 137 HTTP Requests 137 Sending Email 140 Receiving Email 140 Querying an LDAP Directory 141 Adding an LDAP Entry 143 Updating an LDAP Entry 144 Adding and Deleting an LDAP Entry’s Attributes 145 Renaming an Entry 146 Deleting an LDAP Entry 147 Sending a File via FTP 147 Getting a File via FTP 148
12 Using Verity 12.0. 12.1. 12.2. 12.3. 12.4.
151
Introduction 151 Creating a Collection 151 Adding Information to a Verity Collection 152 Searching a Verity Collection with Simple Search 155 Searching a Verity Collection with Explicit Search 157
Contents
13 User Authentication and Authorization 159 13.0. 13.1. 13.2. 13.3. 13.4. 13.5. 13.6. 13.7.
Introduction 159 Logging in a User 160 Logging out a User 160 Authenticating a User 161 Obtaining the Logged-in User ID 162 Authorizing a Block of Code 162 Authorizing a Function 164 Authentication Example 165
Introduction 181 Inserting Data 183 Updating Data 183 Deleting Data 184 Selecting Data 185 Limiting Rows Returned 185 Specifying Multiple Conditions 186 Sorting Results 187 Using Aliases 187 Selecting from Multiple Tables 188 Joining Two Tables 189 Joining Three Tables 189 Grouping Data with CFOUTPUT 190 Performing Outer Joins 191 Selecting Unique Values 192 Using Aggregate Functions 192 Grouping Aggregate Data 193 Limiting Aggregate Results 194 Using the IN Keyword 194 Using IN with Web Forms 195
xiii
xiv
Contents
14.20. 14.21. 14.22. 14.23. 14.24. 14.25. 14.26.
Matching a Wildcard Pattern 196 Matching a Single Character 197 Matching a Group of Characters 198 Matching a Range of Characters 198 Excluding a Group of Characters 199 Excluding a Range of Characters 199 Using Prepared Statements 200
Introduction 203 Writing a Simple Stored Procedure in Microsoft SQL Server 204 Writing a Simple Stored Procedure in Oracle 205 Invoking a Simple Stored Procedure 206 Writing a Stored Procedure with Parameters in Microsoft SQL Server 207 Writing a Stored Procedure with Parameters in Oracle 208 Invoking a Stored Procedure with Parameters 209 Using Output Parameters 211 Working with Multiple Result Sets 213
V Language Extensibility Features 16 User-Defined Functions 16.0. 16.1. 16.2. 16.3. 16.4. 16.5. 16.6.
217
Introduction 217 Declaring a Function 218 Function Arguments 220 Returning Values 222 Suppressing Output 222 Recursive Functions 223 Working with Function References 225
Introduction 229 Creating a Simple Custom Tag 229 Accessing a Custom Tag 230 Using Attributes 230 Returning a Result 231 Adding Start and End Tags 232 Building Nested Tags 234 Encoding Custom Tags 235 Using 236 Using 237
Introduction 239 Creating a Simple Java CFX Tag 240 Using Tag Attributes 241 Setting ColdFusion Variables 244 Using Queries in Java CFX Tags 245 A Simple C++ CFX Tag 247 Using Tag Attributes 250 Setting ColdFusion Variables 251 Using Queries in C++ CFX Tags 253 Installing a Java CFX Tag 256 Installing a C++ CFX Tag 257
Introduction 259 Defining a Component 259 Instantiating a Component 262 Invoking a Component Method 263 Component Inheritance 265 Accessing a Component 267 Using Component Meta Data 268
Introduction 271 Creating a Java Object Instance 271 Invoking Methods on an Object 273 Using Properties on an Object 275 Working with Java Objects 275 Working with COM Objects 276 Working with CORBA Objects 277
Introduction 281 CFML to WDDX 281 CFML to JavaScript 283 WDDX to CFML 285 WDDX to JavaScript 286 Syndicating Content with WDDX 287 Converting a Java Object into WDDX 290 Deserializing WDDX in Java 292
Introduction 295 Creating an XML Object with the Tag 295 Creating an XML Object with the XmlNew() Function 296 Creating an XML Object from Another XML Object 298 Parsing an XML Document 299 Accessing Attributes 299 Accessing Children 300 Accessing Inner Text 300 Technique 300 Comments 301 Searching XML with XPath 301 XSL Transformations 302
Introduction 305 Invoking a Web Service with CFINVOKE 306 Creating an Instance of a Web Service 307 Writing a Web Service 308 Using Properties 309 Deploying a Web Service 311 Invoking a Web Service with .NET 312 Invoking a Web Service with Java 315
Introduction 317 Redirecting to a Servlet or JSP 318 Including a Servlet or JSP 318 Accessing ColdFusion Pages from Servlets and JSPs 319 Sharing Data Between ColdFusion and Servlets/JSPs 320 Accessing Enterprise Java Beans 322
VI Appendixes A Online ColdFusion Resources ColdFusion Web Sites 329 Java Web Sites 331 XML Web Sites 331 Other Useful Web Sites 332
B Security
333
Session Hijacking 333 URL Injection Hacking 334 File Uploading 335 Denial of Service Attacks 335 Cross Site Scripting 336
329
xvii
xviii
Contents
Sandbox Security 337 Security Resources 337
C Migrating from ColdFusion 5 to ColdFusion MX 339 ColdFusion Code Compatibility Analyzer 339 ColdFusion Settings Migration Wizard 339 Changes to CFML Tags and Functions 340 Database Operations 340 Localization 340 References 340
D Converting Between Tags and Scripting 341 The Tag 341 If-Then Statements 343 Loops 343 Switch Statements 345 Exception Handling 346
Index 347
About the Authors Pete Freitag is the co-founder and Chief Technology Officer of CFDev, a company that builds Web components for ColdFusion and other languages. He has several years of experience developing database-driven Web applications, integrating with legacy systems, and product development. He contributes to the ColdFusion,Web development, and software development communities regularly, and holds a BS in Software Engineering from Clarkson University. Brad Leupen is the Chief Technology Officer for the software company Noverant. He holds an AB in Computer Science from Harvard University, where he focused on operating systems and distributed systems research. He won the Derek Bok Award for Excellence in Teaching as a Teaching Fellow for several university undergraduate classes. He has closely followed the development of key Web technologies and standards, including J2EE, .NET, and XML. Chris Reeves is a software developer for Religent, Inc. in Raleigh, NC, where he assists in development for the company’s remote systems management software suite. He graduated with a BA in English from Appalachian State University.
Acknowledgments I would first like to thank my co-authors—Brad and Chris—for sharing in the joys and pains involved in putting this book together.They both exerted a great deal of energy and sacrificed lots of time for this project. I also owe thanks to Sams Publishing for providing me with several great editors to work with. In addition I’d like to thank Bob Kern and TIPS Technical Publishing for their hard work. I’d like to thank my co-workers at CFDev and ActivSoftware for giving me the flexibility I needed while working on this project. I must also thank my brother Steve for introducing me to the industry and providing me with knowledge and resources. Additionally, Dr. Douglas MacIntosh shared much of his knowledge and wisdom with me. Finally, I’d like to thank everyone involved in the ColdFusion community for providing a synergistic environment for learning about ColdFusion. —Pete Freitag I would like to thank the folks at Sams Publishing for their hard work in this project. I would also like to thank Chris and Pete. It was a joy to work with you. Finally, I would like to thank Bob Kern and the employees of TIPS Technical Publishing. None of this could have happened without you. —Brad Leupen Thanks to my co-authors Brad and Pete for their outstanding work.Thanks also to everyone involved with this project at Sams Publishing as well as Bob Kern and the good folks at TIPS Technical Publishing. —Chris Reeves
We Want to Hear from You! As the reader of this book, you are our most important critic and commentator.We value your opinion and want to know what we’re doing right, what we could do better, what areas you’d like to see us publish in, and any other words of wisdom you’re willing to pass our way. You can email or write me directly to let me know what you did or didn’t like about this book—as well as what we can do to make our books stronger. Please note that I cannot help you with technical problems related to the topic of this book, and that due to the high volume of mail I receive, I might not be able to reply to every message. When you write, please be sure to include this book’s title and author as well as your name and phone or email address. I will carefully review your comments and share them with the author and editors who worked on the book. Email: [email protected] Mail: Mark Taber Associate Publisher Sams Publishing 201 West 103rd Street Indianapolis, IN 46290 USA
Reader Services For more information about this book or others from Sams Publishing, visit our Web site at www.samspublishing.com.Type the ISBN (excluding hyphens) or the title of the book in the Search box to find the book you’re looking for.
Introduction
T
he ability to produce applications with relative ease, power, and speed spawned the popularity of ColdFusion, and is the reason many people use the technology.This book attempts to further strengthen these assets by opening your eyes to the power of ColdFusion, and at the same time accelerating the ease and speed at which you develop ColdFusion applications. This book is not meant to introduce you to ColdFusion, rather it is meant to enrich your development experience with solutions to everyday problems.We wrote this book for developers already familiar with the basics of ColdFusion and programming. Several books available today do a fine job of explaining what a conditional is, as well as how to set a variable.We felt no need to reinvent the wheel with this book; it seemed better to complement your current ColdFusion library with an arsenal of solutions to everyday problems.
How This Book Is Organized This book is organized in such a way that it should be useful to experienced ColdFusion developers as well as beginners. Each chapter is broken into problem-oriented sections. The sections are then broken down further into two parts: “Technique” and “Comments.” The technique portion of each section asserts a one- or two-sentence solution to the problem presented in the section, followed by a short code sample.The technique section aims to quickly provide a solution to the problem with as few words as possible. This approach is especially friendly to experienced developers looking to find a quick solution to a particular problem. Novice developers may also find it helpful to see a solution to the problem upfront. The comments part of each section serves to describe the problem and its solution in detail. In the comments sections, you will find an explanation of the code presented in the technique, along with additional information pertaining to the tags or functions used to solve the problem.Within the comments, developers will find tips, tricks, and pointers to additional information.
How to Use This Book This book is not intended to be read sequentially or cover to cover. Rather, when a problem arises, you should use the Table of Contents or Index to find the appropriate recipe and apply it.
2
Introduction
Although you wouldn’t start using a traditional cookbook if you didn’t first know how to use your oven, this cookbook also is not meant to be an introduction to core principles. Several books are currently on the market that can help you get started with ColdFusion. In addition to this book and other books, the ColdFusion documentation is also a good source of reference and explanations. If you chose to install it, the ColdFusion documentation can be found in the /cfdocs directory of your Web root. ColdFusion documentation can also be found at livedocs.macromedia.com, which augments the documentation with comments posted by developers.The comments are often helpful to clarify the use of a particular function, or to verify documentation bugs.
Chapter Overviews Chapter 1, “String Manipulation,” includes several basic problems such as string concatenation and substring formation.The chapter also covers more complex problems such as using regular expressions. Chapter 2, “Working with Lists,” explains what lists are, how to create them, and how to work with them. Some of the problems solved include looping through a list, searching a list, and changing the list delimiter. Chapter 3, “Arrays,” handles the creation, manipulation, and iteration of the array data type in ColdFusion. Chapter 4, “Structures,” covers the structure data type.The topics covered include notation, sorting, populating, and copying structures. Chapter 5, “Queries,” shows you how to output the contents of a query object, how to create a query programmatically, and how to run queries of queries. Chapter 6, “Dates and Times,” covers date and time formatting, date math, and locales. Chapter 7, “Application Flow,” covers the tag. It explains state management with sessions, and discusses client variables. Chapter 8, “Exception Handling,” shows how to catch, throw, and re-throw exceptions. Chapter 9, “Charting Data,” explains how to create charts with the tag. Chapter 10, “Files and Directories,” shows how to create, manipulate, and read files and directories. Chapter 11, “Using Internet Protocols,” covers the HTTP, LDAP, FTP, and email (SMTP, POP) protocols, and how to use them with ColdFusion. Chapter 12, “Using Verity,” shows you how to create and search a verity collection. Chapter 13, “User Authentication and Authorization,” takes you through the problems and solutions encountered when managing users in an application. Chapter 14, “Structured Query Language (SQL),” explains how to use many of the features in the SQL language to query databases. Chapter 15, “Stored Procedures,” shows you how to create stored procedures and invoke them in ColdFusion. Chapter 16, “User-Defined Functions,” details the procedures necessary to create your own functions in ColdFusion.
Introduction
Chapter 17, “ColdFusion Custom Tags,” explains how to create your own tags in ColdFusion. Chapter 18, “CFX API Custom Tags,” explains how to create your own tags in ColdFusion using Java and C++. Chapter 19, “Components,” shows you how to create, instantiate, invoke, and access ColdFusion components or CFCs. Chapter 20, “Objects,” explains how to use Java, COM, and CORBA objects in your ColdFusion applications. Chapter 21, “WDDX,” describes how to use WDDX to serialize data in XML and pass it between applications. Chapter 22, “XML,” shows you how to extract data from XML, and how to transform XML documents with XSL. Chapter 23, “Web Services,” explains how to invoke and create Web Services. Chapter 24, “J2EE Interoperability,” explains how to work with J2EE technologies such as servlets, JSP, and EJB. Appendix A, “Online ColdFusion Resources,” lists and describes resources for ColdFusion developers available online. Appendix B, “Security,” outlines some common security vulnerabilities, as well as possible solutions. Appendix C, “Migrating from ColdFusion 5 to CFMX,” describes procedures you can take to migrate your code to work optimally on CFMX. Appendix D, “Converting Between Tags and Scripting,” shows you how to write logic with blocks instead of with tags.
3
I Datatypes and Containers 1
String Manipulation
2
Working with Lists
3
Arrays
4
Structures
5
Queries
6
Dates and Times
1 String Manipulation
1.0.
Introduction
No programming concept in the history of modern computing has appeared as overcomplicated as string manipulation. How many of you C programmers have secretly wondered why strings are so tough to use? malloc()? free()? strcat()? What? “I just want to combine two words!” you might say to yourself, although not loud enough for other programmers to overhear. Strings in C are represented as discreet arrays of characters, or bytes. If the length of your string exceeds that of the array, watch out! CGI programs, in particular, bring out the worst in C’s low-level string API. Debugging memory leaks in your string-handling code can be particularly frustrating when that is all your program does. Fortunately, the ColdFusion Markup Language (CFML) makes working with strings a lot easier. Strings are the default data type in CFML and the language offers a rich library of functions and operators specifically designed to play with strings. This chapter will explore many of these APIs as it describes how to solve many typical programming problems.The chapter will start slow but the examples will quickly move into some more advanced techniques, such as regular expressions.
1.1.
Concatenating Strings
You want to combine two strings.
Technique Use the & operator to combine two strings into one. #s#
8
Chapter 1
String Manipulation
Comments The & operator combines the two strings, “Hello” and “World!”, to create a new string, “Hello World!”.The new string is then output to the resulting Web page by using the … tags. Notice that you don’t have to worry about the length of the final string.The ColdFusion application environment handles allocating the memory for you.
1.2. Delimiting Strings You want to represent many text fields as a single string.
Technique You can create a simple comma-delimited list in ColdFusion by combining the different variables and delimiters.
Comments In this example, you have created a comma-delimited list by joining the x and y variables.The comma-delimited string is stored in the variable z. If you have ever written a program to import data into a database, you know the joys of working with delimited strings. As long as Microsoft Excel is around, CSV files may well remain the data interchange format of choice. In fact, delimited strings hold a place near to ColdFusion’s heart as well.The CFML language includes an entire list processing library geared toward splicing and dicing delimited strings.You’ll learn about support for list processing library in great detail in Chapter 2, “Working with Lists.” However, let’s take a moment to see just how to create a delimited string, or list. The key to a delimited list is (surprise!) the delimiter.The list uses a common delimiter (usually a comma or a tab character) to segregate a string into a series of substrings. Quite often, data files will include multiline delimited strings, where each line represents an individual data record and each delimited substring represents a unique field value.
1.3.
Using ASCII Character Codes
1.3. Using ASCII Character Codes You want to specify ASCII characters by their numeric value.
Technique Use the Chr() function to display a characters by their ASCII character code. #string#
The Chr() function returns the character that corresponds to a given ASCII character code.The following example inserts the copyright symbol ([cr]) into a line of text by referencing its ASCII character code. The resulting Web page will faithfully render the string “Copyright [cr] 2002” just as the code implies. This is particularly useful for embedding special characters (such as carriage returns and line feeds) into strings. ColdFusion also provides the Asc() function, which returns a character’s numeric value. To display the alphabet, use the Asc() function to find the beginning of alphabet, and then loop to the end, displaying each character with the Chr() function. #charUpper# --> #charLower#
Comments Rather than type 52 letters into the source file, you can do this by taking advantage of the fact that alphabetic characters are represented by a contiguous numeric sequence in the ASCII character set. (The observant reader may note that this algorithm requires 227 characters.) The first step is to obtain the beginning ASCII number by using the Asc() function to find the ASCII equivalent of the uppercase letter A. Adding 25 to this value will then result in the number of the letter Z.You then iterate over this range by using the tag. For each number in the range, you find the corresponding character by using the Chr() function.You can discover the numeric code of the lowercase version of the letter by adding an offset of 32.The fruits of your labor look something like this: A B . Z
--> a --> b . . --> z
9
10
Chapter 1
String Manipulation
1.4. Forming Substring You want to divide a string into smaller substrings.
Technique Use the Right() and Left() functions to form substrings. #str# #i# #i#
Comments This example starts with the string “The quick brown fox jumped over the lazy dog.” It then asks the users to select a number between 1 and 45, which will be used as the pivot point in the string. Once the number is submitted, the ColdFusion
1.4.
Forming Substring
template creates two new strings.The first string is the result of performing a Left() function on the string to take the first n characters up to, and including, the pivot point. The second is the result of a Right() function, which takes all of the characters to the right of the pivot point. Finally, the page swaps the two substrings and displays the result to the users.The new, rotated string is used as the starting point the next time the users submit the page. ColdFusion MX includes a number of utility functions for dissecting, rearranging, and assembling strings.These functions are listed in Table 1.1. Table 1.1 CFML Substring Functions Find(substring, string [, start])
Finds the first occurrence of a substring within a string, beginning at an optional start position.The search is case-sensitive. Returns the position of the substring within the string, or 0 if the substring is not found. Same as Find() except that the search is not case-sensitive. Finds the first occurrence of any one of a list of characters within a string. Returns the position of the first character found in the string, or 0 if none of the characters appears in the string. Returns a substring of specified length, starting at the beginning of the string. Returns the length, in characters, of the specified string. Returns the specified string stripped of the leading spaces. Returns a substring of length count beginning at position start in the specified string. Returns a copy of the string with count characters removed, beginning at position start. Replaces one or more occurrences of substring1 with substring2 in string.The search is case-sensitive. Replaces one or more occurrences of substring1 with substring2 in string.The search is not case-sensitive. Returns count characters from the end of the string. Returns the string with all trailing spaces removed.
11
12
Chapter 1
String Manipulation
Table 1.1 Continued StripCR(string) Trim(string)
Returns the string with all return characters removed. Returns the string with all leading and trailing spaces removed.
1.5. Encrypting Strings You want to encrypt a string.
Technique Use the Encrypt() and Decrypt() functions to encrypt or decrypt strings. Encrypted String: “#encryptedString#” Decrypted String: “#decryptedString#”
Comments You might find it necessary to encrypt and decrypt strings for storage or for transmission across a network.The CFML language includes two functions to aid in this effort: Encrypt() and Decrypt().The encryption algorithm used by the functions is based on a private key and the algorithm’s security is tied to the security of the key. Note that this approach differs in this way from the public-key encryption techniques used in the popular RSA encryption algorithm. The syntax for both of these functions is straightforward. Encrypt() takes two strings as arguments: the string to be encrypted and a key to be used in the encryption process.The function returns an encrypted string, which can be (and usually is) much longer than the original.The Decrypt() function also takes two strings as arguments: the encrypted string to be decrypted and the key that was used to encrypt the original string.The function reverses the encryption algorithm and returns the original string as a result. Note the importance of using the same key when calling the Encrypt() and Decrypt() functions. Be sure not to expose this key to outsiders, as malicious users can then thwart your security efforts! The result of executing this page looks like this:
Although the Encrypt() and Decrypt() functions are technically secure in and of themselves, limitations in private key security can make them undesirable for use in ecommerce applications.The sender and receiver must agree on a common key before a message can be encrypted.The sharing of this key is often insecure, thereby compromising the security of the entire transaction. However, ColdFusion string encryption is perfectly fine for protecting simple data elements. It is more than suitable for disguising, say, system variables in a page’s URL.Use the Encrypt() and Decrypt() functions to encrypt or decrypt strings.
1.6. Hashing Strings You want to hash, or forward-encrypt, a string for comparison purposes.
Technique Use the Hash() function to encode a string. You entered the correct password. Password attempt failed. Please try again. Enter your password:
Comments In addition to the Encrypt() and Decrypt() functions, ColdFusion MX provides a forward-encryption function called Hash(). Hash() uses the MD5 algorithm to encrypt a string.The Hash() function is useful for tasks such as storing a password
13
14
Chapter 1
String Manipulation
securely and comparing user-supplied passwords against the stored copy.The one-sided nature of the Hash() function means that the original password cannot be directly reproduced with a copy of the hashed password.The only way somebody can crack it is to test the Hash() function on every possible password string. The previous example illustrates the use of the Hash() function to forward-encrypt and compare a user-supplied password with the original.This program returns success only if the user enters the string “password”.
1.7. Iterating Through a String You want to loop over each substring in a single string.
Technique Use the tag and the Mid() function to iterate over a string. #newstring# Enter text to be reversed:
Comments CFML allows you to inspect individual characters within a string. For example, let’s say that your boss has asked you to write a Web page that reverses a user-defined string.The first question you need to ask yourself is: “Why am I working here?”The second question should be: “How can I use CFML to do this?” The reversal algorithm is simple: you loop from 1 to the string’s length and use the Mid() function (which you learned about earlier) to extract the character at each position in the string.The character is prepended to a resulting string, which you show to the users (and your boss) when you are finished.
1.8.
Reading a File Line by Line
Lazy programmers would take the easy way out and use the CFML function Reverse() to do this.
1.8. Reading a File Line by Line You want to parse an input file into separate lines of data.
Technique Use and to iterate over a file, line by line. #line#
Comments This example reads a small text file and parses it into multiple lines of data.The trick to this is to treat the entire file as a delimited text string and use the tag to iterate over a list of lines.You can use the carriage-return and line-feed characters as the delimiters in your string. The first two lines of the template read a file called data.txt (see Chapter 10, “Files and Directories,” for more information on file I/O). expects the filename argument to be an absolute path name, so you might want to use the GetCurrentTemplatePath() function to handle relative paths. The last three lines form the heart of this little program.These lines call the tag, specifying the list attribute.This type of loop will iterate over a delimited string. In this case, the string contains the data file.This example uses the string “#chr(10)##chr(13)#” (line feed and carriage return) as the delimiter (UNIX users may just require “#chr(10)#”).This technique will cause the loop to iterate over each line in the file, assigning the contents of the line to the variable line in the program. It then prints the line and continues. One of the reasons that ColdFusion has been so popular for so long is its vast library of I/O tags and functions. ColdFusion is an excellent platform for moving data from one data repository to another. It is incredibly easy to access information in file systems, databases, FTP/HTTP sites, LDAP directories, mail servers, and so on.
15
16
Chapter 1
String Manipulation
1.9. Searching a String You want to search a string for occurrences of a specific substring.
Technique Use the Find() and FindNoCase() functions to search a string. The string #searchstring# appeared #cnt# time(s).
Enter a string to search for: Case sensitive?
1.10.
Replacing Substrings within a String
Comments ColdFusion includes a nice string-searching utility that allows you to test for certain substrings within a larger string.These searches can be case-sensitive or case-insensitive, depending on your mood.You should familiarize yourself with two functions: Find() and FindNoCase().They will come in handy at some time or another, so you might as well learn them now. In the following example, you create a small application that enables you to search for strings in Chapter 4 of Alexandre Dumas’ The Three Musketeers, in which the hero, d’Artagnan, meets the Royal Musketeers—Athos, Porthos, and Aramis—for the first time. This example prompts the users to enter a search string. It will then load the chapter’s text into memory and count the number of times the search string appears. In order to count each occurrence of the string, you must make use of the optional start parameter for the Find() and FindNoCase() functions.The idea is to call the Find() function repeatedly, passing the result of the preceding function call (the starting position of the substring) as the new search starting position. In other words, make Find() resume the search where it stopped before. Be sure to avoid an infinite loop by adding “1” to the start position each time through!
1.10. Replacing Substrings within a String You want to replace instances of a substring with another substring.
Technique Use the Replace() and ReplaceNoCase() functions to replace a substring with another string.
17
18
Chapter 1
String Manipulation
#str# Replace this string: With this string:
Comments The Replace() and ReplaceNoCase() functions take as arguments a string to be searched, the substring to be replaced, the substring to do the replacing, and an optional scope parameter. The scope parameter dictates whether the function should replace all occurrences of substring1 with substring2 (“all”) or just the first occurrence (“one”). Be careful—the default behavior of Replace() and ReplaceNoCase() is to replace just the first occurrence. Be sure to use the “all” scope option if you intend to perform a global search and replace. The previous example attempts to make a popular tongue-twister more manageable by replacing “peppers” with some other vegetable. Use the Replace() and ReplaceNoCase() functions liberally to child-proof your Web bulletin board!
1.11. Using REFind() to Perform a Literal String Search You want to search for a substring within another string.
1.12.
Using Qualifiers to Indicate Multiplicity
Technique Use the REFind() function to perform a literal string search.
Comments This will return the value 5, indicating the start position of the first occurrence of the substring “Sun” in the string “The Sun Also Rises”. ColdFusion’s regular expression functionality lies within the functions REFind, REReplace, REReplaceNoCase, and REFindNoCase. In the case of literal text searches, the functions operate just like their “sans-RE” counterparts.
1.12. Using Qualifiers to Indicate Multiplicity You want to use the *, ?, and + symbols to specify a character’s multiplicity.
Technique Use the *, ?, and + quantifiers to indicate the multiplicity of the preceding character. REReplace(“Please pahhk the cahhh in the Hahvahd Yahhhd”,“ah+”, “ar”, “all”)
Comments There are three common symbols used as quantifiers here: *, ?, and +.They are appended to a character (or a group of characters) to indicate how many times that character should appear in the search string.The * quantifier represents “zero or more.”The ? quantifier represents “zero or one.” Finally, the + character represents “one or more.” Let’s look at a few examples, the first of which I like to call the “Bostonian Translator.” The previous example returns the correct spelling of the phrase “Park the car in the Harvard Yard”. How does this work? Is it because Allaire used to be headquartered in Cambridge? Nope.This works because you tell it to.The example tells ColdFusion to look for an a followed by one or more hs and to replace them all with the string “ar”. What would happen if you used the * quantifier instead of +? REReplace(“Please pahhk the cahhh in the Hahvahd Yahhhd”,”ah*”, “ar”, “all”)
This is no good. Instead of English, you get the phrase “Plearse park the car in the Harvard Yard”. Plearse? The problem is that the regular expression parser did what you told it to do. It looked for an a followed by zero or more hs. It found the single a in “Please” and replaced it.
19
20
Chapter 1
String Manipulation
1.13. Using Wildcards You want to use the ., ^, and $ characters to represent other characters.
Technique Use the ., ^, and $ characters to represent other characters. REReplace(“a man, a plan, a canal, panama!”,”^a”, “The”, “all”)
Comments The special characters ^ and $ represent the beginning and the end of the string, respectively. The example will return the string “The man, a plan, a canal, panama!”. Only the a at the very beginning of the string changed. The . (dot) character is used to represent any possible character, including whitespace and newlines. For example, the pattern .ort can match the words fort, port, tort, but not ort. However, the pattern .*ort will match fort, report, ort, retort, and so on.
1.14. Using Brackets You want to use the bracket characters ([]) to represent a subset of characters.
Technique Use brackets [] to represent a subset of characters.
Comments This expression looks for a space, followed by any uppercase letter, followed by the lowercase letter l.The bracketed expression [A-Z] serves as a wildcard to the regular expression parser to indicate: “any uppercase letter in the range of A to Z.”There is an implicit or among strings of letters in brackets.The pattern [dl]og will match dog and log but not dlog. Adding a ^ (caret) to the beginning of the bracketed clause will impose a negation on the characters contained in the brackets. For example, [^dl]og will match any sequence ending in og that is not preceded with a d or an l. The brackets also allow you to specify a range of characters using the — (dash) character. Here’s an example using the — character: [0-9]?[0-9]/[0-9]?[0-9]/[0-9][0-9]
1.16.
Escaping Special Characters
Can you figure out what it is matching? It matches dates. It can match 1/1/01 or 12/12/02 using the ? quantifier because the first digit of the month and day is optional.
1.15. Performing OR Operations You want to use the pipe (|) character to perform a logical OR operation and to group characters.
Technique Use the | (pipe) character and parentheses to perform a logical OR operation, as well as to group characters.
Comments The | (pipe) special character is used as a logical OR. Each character in the pattern is intrinsically joined with a logical AND, unless explicitly specified with the | character. If you wanted a regular expression to match car or bar, you could use the pattern c|bar. You might have noticed with that last example that you could have also matched car or bar using brackets “[cb]ar”. It turns out that the | character has other uses; it can be used to match sequences of characters as well.This is done with the parentheses ( ) characters. Parentheses are used to group characters. Here’s an example using parentheses and the | character: (Mon)|(Tues)day
This example matches Monday or Tuesday.
1.16. Escaping Special Characters You want to use the backslash (\) character to escape special characters.
Technique Use the backslash (\) character to escape special characters. You entered an invalid email address.
Comments The \ character is used for escaping any quantifiers or special characters. Let’s look at a practical example, which validates an email address.To build this pattern, you deconstruct
21
22
Chapter 1
String Manipulation
the email address. Email addresses start with a username .+. Next comes the @ sign, .+@, and then a domain name that contains at least one dot (you need to escape it). Therefore, .+@.+\..+ is the correct pattern. Here’s a code snippet that you can use: The \ character is also used for a very handy feature called the back reference. It allows you to use your groups (patterns in parentheses) again in your pattern or in your replacement.The back reference \1 represents the first group, \2 represents the second, and so on. Here’s an example that eliminates repeated words: REReplace(“Echo Echo”,”(.+) +\1”,”\1”,”ALL”)
1.17. Using Character Classes You want to use character classes to represent a predefined subset of characters.
Technique Use character classes to represent a predefined subset of characters.
Comments The last group of special characters are known as “character classes.” Character classes are keywords that represent a predefined class of characters. One example is [[:alnum:]], which is the same as [a-zA-Z0-9].They are listed in Table 1.2. Table 1.2 Regular Expression Character Classes Character Class
Matches
:alpha:
Any letter Any uppercase letter Any lowercase letter Any digit (0–9) Any alphanumeric character Any hexadecimal digit A space or tab. A space, tab, newline, carriage return, or line feed Any printable character. Any punctuation character All printable characters except those in the space character class All characters not in the upper, lower, alpha, digit, punct, graph, print, or xdigit classes
The last chapter discussed how ColdFusion gives special treatment to delimited strings. These strings are even given a special nickname: lists.The following string is an example of a ColdFusion list: apple,orange,grape,banana,peach
Lists, such as this list of fruit, are wonderful data structures in ColdFusion.They are plain text, so they are easy to assemble.They are also common. Data import files often contain lists. Better yet, HTML check boxes submit their results as comma-delimited lists. Finally, ColdFusion provides a complete function library for manipulating lists. Once familiar with them, you will find yourself using ColdFusion lists throughout your CFML templates.They are simple yet powerful and are another reason why the CFML language is so popular among non-programmers. This chapter looks at some common programming tasks involving lists. In doing so, it explains key list concepts and includes some practical examples.
2.1. Creating Lists You want to create a list.
Technique Use delimited strings to create lists. Lists are very easy to create.You can create a list of fruit in one line of code:
24
Chapter 2
Working with Lists
Comments You can create the same list iteratively by tacking on values one at a time.
You can also use the ListPrepend() and ListAppend() functions to add elements to the beginning and end of a list, respectively. Both functions take as arguments the list, the value to be added, and an optional delimiter (again, the comma is used as the default). Both functions also return a copy of the list with the new item.Thus, you can substitute this line:
with:
Note The ColdFusion documentation actually discourages the use of ListAppend() and ListPrepend() in favor of manually adding items to a list. Unfortunately, it does not give the reason why.
Like Peter Parker’s spider or Pamela Anderson’s surgeon, the delimiter is the source of a list’s power.You can choose any character you like as a delimiter, although the comma is the default in ColdFusion. Be sure to choose one that you like because it is important that you maintain a consistent delimiter in your list.
2.2. Changing Delimiters You want to change the delimiter that a list uses.
Technique Use the ListChangeDelims() function to change a list’s delimiter. List 1: #list1# List 2: #list2#
2.3.
Extracting Elements
Comments It was love at first sight.Your delimiter seemed to be perfect for your list when you first started going out. Alas, you caught your delimiter cheating with certain list elements and it is now time to move on.What is to be done? Fortunately, ColdFusion makes it easy to extract yourself from this potentially awkward situation.The ListChangeDelims() function will clean up your mess. Simply pass it the list you want to change, the new delimiter, and (optionally) the old delimiter and you are back in business.Who said breaking up is hard to do? This function is used to change the delimiter from a comma (,) to a pipe (|).This can be useful when you anticipate using the delimiter as a part of a data element in the list.
2.3. Extracting Elements You want to extract specific elements within a list.
Technique Use the ListGetAt() and ListToArray() functions to extract elements in a list.
fruit 3: #thirdfruit# fruit 4: #fourthfruit#
Comments There are two primary ways to extract elements from a ColdFusion list.The most popular way is to use the ListGetAt() function. ListGetAt() takes a list, a position, and an optional delimiter as its arguments. It returns the value that is found at the specified position in the list. You use this technique previously to extract the third fruit element in the list:
Note ColdFusion lists use cardinal (or one-based) numbering. Therefore, you should use the index 1, not 0, to reference the first element in a list.
25
26
Chapter 2
Working with Lists
The second way to inspect the contents of a list is to convert the list into an array and use array indexing to retrieve the values.The ListToArray() function performs the conversion for you. Pass the function a list and an optional delimiter and it will return an indexed array.You can use this approach in the current example to get the fourth fruit:
The use of arrays is covered in much more detail in the next chapter. However, you can see that the expression fruitarray[4] is much easier on the wrists than ListGetAt(fruitlist,4). Converting your list into an array is a nice technique when you will be extracting many elements from a single list.There is a potential performance boost to this as well, because indexed lookups take less time than do linear searches in a list. However, make sure that you are done modifying the list before you convert it into an array. ColdFusion makes a copy of the list when it converts it. If you make changes to the list following the conversion, you must re-convert the list or else make the same changes to the array. ColdFusion also supplies the following three functions to access the contents of a list—ListFirst(), ListRest(), and ListLast(). ListFirst() returns the first element of a list. ListLast() returns the last element of a list. ListRest() returns a list without its first element. LISP programmers might recognize ListFirst() and ListRest() as the car and cdr functions of the recursive LISP programming language. Note Use the Trim() function to remove extra spaces surrounding delimiters in your list.
2.4. Handling Empty Values You want to handle empty values in your list.
Technique Use a custom function to fix null values in a list. function ListFixNulls(list,delim) { ar = ArrayNew(1); theval = “”; thechar = “”; pos = 1; for (i=1; i lte Len(list); i = i + 1) { thechar = mid(list,i,1);
2.4.
if (thechar is delim) { ar[pos] = theval; pos = pos + 1; theval = “”; } else { if (thechar is not chr(0)) { theval = theval & thechar; } } } if (not(arrayisempty(ar)) or theval is not “”) { ar[pos] = theval; } return ar; } With ListFixNulls()...
ID: #id# First Name: #firstname# Middle Initial: #middle# Last Name: #lastname# Without ListFixNulls()... ID: #id# First Name: #firstname# Middle Initial: #middle# Last Name: #lastname#
Handling Empty Values
27
28
Chapter 2
Working with Lists
Comments Most historians attribute the ancient Indian mathematician Brahmagupta (598–670 AD) with the introduction of the number zero to modern numbering systems. He forever changed the way mathematicians think by recognizing the importance of acknowledging the “null value” in any mathematical system. Unfortunately, the works of Brahmagupta were not consulted during the design phase of the ColdFusion lists implementation. CFML list-processing functions completely disregard the null value, a fact which has long irked this ColdFusion developer. For example, consider the following table of employee names and IDs: Employee ID,First Name,Middle Initial,Last Name 10001,John,H,Smith 10002,Jane,,Smith 10003,George,O,Smith
Although John and George both have middle initials, Jane does not. ColdFusion will throw an “Invalid List Index” exception when you try to access the fourth element of Jane Smith’s list.The ListGetAt() function essentially removes all null values from the list (for example, “1,2,3” is equivalent to “1,,,,2,,,,,,,,3”).Thus, the template returns the string “Smith” as the third element of the list instead of returning an empty string, as one might expect. This phenomenon becomes a nightmare when dealing with associated lists that may contain null values (like most data imports). Fortunately, there is a work-around.The previous technique shows a custom function (see Chapter 16, “User-Defined Functions,” for more about user-defined functions) that converts a list into array while preserving the list’s null values.This function takes as arguments a list and a delimiter character and returns the new array. The function must not rely on the ColdFusion List API because those functions will ignore null values. Instead, it must examine each character in the list and build the array values manually. Note that the function will not work with multi-character delimiters. I leave this up to you to implement.
2.5. Changing Values in a List You want to change the values of specific elements within a list.
Technique Use the ListInsertAt(), ListSetAt(), and ListDeleteAt() functions to modify the contents of a list.
2.6.
Searching a List
Originial List: #list# With Element Inserted: #list1# With Element Set: #list2# With ElementDeleted: #list3#
Comments Updating lists in ColdFusion is even easier than creating them. Use the ListInsertAt() function to insert a new value into your list.The function takes the
list you are updating, the position you want to change, the value you want to insert, and an optional delimiter as arguments.The function confirms that you have supplied a valid list index and inserts the new value at the specified position, moving the original element and all subsequent elements over one spot in the list. The ListSetAt() function uses the same syntax as ListInsertAt() but its behavior is slightly different. ListSetAt()replaces the old element at the specified position with the new element. The ListDeleteAt() function is the third list-modification function.The arguments for the ListDeleteAt() function are the list to be modified, the position that should be removed from the list, and an optional delimiter. ListDeleteAt() will return a copy of the list sans the element at the specified position. The previous technique uses these functions to modify a single list in three ways.
2.6. Searching a List You want to search a list for specific values.
Technique Use the ListFind() and ListFindNoCase() functions to search the elements of a list. The element was found at position #pos# in the list.
Comments How can you determine whether a given list contains a specific element? Once again, CFML comes to the rescue by giving you the ListFind() and ListFindNoCase() functions.The arguments to both functions are the same: a list to search, a value to search for, and an optional delimiter to use when searching.These functions return the index of the first element that matches the specified value. ListFind()performs a case-sensitive search, whereas ListFindNoCase() does not.
29
30
Chapter 2
Working with Lists
The template in the previous example searches a list for the element “grape”.The ListFind() function returns the number 3 to indicate that the element in question resides in the list’s third position.
2.7. Sorting a List You want to sort the elements in a list.
Technique Use the ListSort() function to sort a list. #sortedlist#
Comments CFML also gives you the capability to sort your lists.The ListSort() function allows you to sort a list of elements in different ways.The arguments to ListSort() are the list to sort, the sort type (that is, numeric, text, and textnocase), the sort order (such as asc[ending] or desc[ending]), and an optional delimiter. ListSort() returns a copy of the sorted list. The previous technique shows a template that performs an ascending text sort on a list.The result of the function is this list: “apple,banana,grape,orange,peach”. Note Macromedia introduced a subtle change to the ListSort() function in the new MX server. When using the textnocase and desc options, MX returns elements that differ only in case in the opposite order as when the textnocase and asc options are used. Older versions of ColdFusion did not change the ordering of elements that differed only in case.
2.8. Adding Qualifiers to a List You want to add qualifiers to the elements within a list.
Technique Use the ListQualify() function to qualify the elements of a list. #qualifiedList#
2.9.
Looping Through a List
Comments Delimiters are a necessary evil in any list. A poorly chosen delimiter can render a list useless. Imagine using the letter a as a delimiter in a list of names.That probably would not work so well.The perfect delimiter is one that will never appear in the list’s data. Choosing this delimiter usually requires a prior knowledge of the characters that will appear in the list. What should you do, then, if the element data in your list requires that the delimiter appear in the data fields as well? One technique you can use is to qualify the elements in your list. Qualifying a list means using additional characters, other than the delimiter, to isolate the different elements. Single and double quotes are common list qualifiers. Consider the following list of addresses: 8317 Morgans Way,1128 Blenheim Dr,804 W. Morgan St, Apt X2C
The string “Apt X2C” is clearly a continuation of the “804 W. Morgan St” address and not an address on its own.You can eliminate this ambiguity by qualifying the elements in the list: “8317 Morgans Way”,”1128 Blenheim Dr”,”804 W. Morgan St, Apt X2C”
ColdFusion includes a function, ListQualify(), that will surround a list’s elements with a qualifier of your choosing.The function accepts a list, a character or string qualifier, an optional delimiter, and an optional elements argument.The all elements option will put qualifiers around all elements in the list; the char option will put qualifiers around alphabetic strings (numeric fields usually do not require qualifiers). The example shown in this technique adds qualifiers to a list to produce the following output: ‘apple’,’orange’,’grape’,’banana’,’peach’
ListQualify() is a nice function to use when you are preparing a large list of data for
import into a database. Many import routines actually expect data to be in a qualified (quote-comma-delimited) format.
2.9. Looping Through a List You want to iterate over each element in a list.
Technique Use the tag with the list attribute to iterate over the elements in a list. #fruit#
31
32
Chapter 2
Working with Lists
Comments My favorite list-related feature in ColdFusion is the built-in support for looping over a list of elements.The simplist way to do this is to use the tag and to specify its list attribute. The list attribute is, perhaps, the tag’s finest asset. In this mode, expects the following attributes: index (required—the variable name to which each list element will be assigned), list (required—the list that is to be looped), and delimiters (optional—one or more delimiters to use in iterating over the list).The tag will execute its body n-times, where n equals the number of elements in the list. Upon each iteration, the loop will assign the next element in the list to the variable named by the index parameter. The tag will iterate over each fruit in the list, assigning a new value to the variable fruit each time.The page output generated by the templates looks like this: Apple orange grape banana peach
2.10. Looping Over a Structure’s Key List You want to iterate over the keys contained in a structure.
Technique Use the tag to iterate over a structure’s keylist.
#key# = #value#
Comments The tag can be used to examine the contents of a structure. Structures, which are covered in better detail in Chapter 4, “Structures,” are hash tables that contain an
2.11.
Looping Until a List Is Empty
unlimited number of key/value pairs.You can use the StructKeyList() function to acquire a list of entry keys in a structure.You can then use the tag to iterate over these keys and evaluate the entry in the structure.The code shown in this technique creates a simple structure representing an employee and examines its contents by using the tag.The template produces the following output: STATE = LA LASTNAME = Hackney ID = 10001 MIDDLENAME = Allen CITY = Red Stick FIRSTNAME = Ryan
2.11. Looping Until a List Is Empty You want to perform a conditional loop on a list that might change.
Technique Use the tag and its condition attribute to loop over the contents of a dynamic list. #fruit#
Comments Another way to loop over a list is to use the tag with its condition attribute in concert with the ListFirst() and ListRest() functions.This is useful when you will be modifying the contents of the list inside the body of the loop.The algorithm is to pop off the first element of the list continuously until the list is empty.The example in this section implements this strategy. In the example, fruitList is constantly reduced in size by assigning it the result of the ListRest() function.You therefore have greater control over the contents of the list and the behavior of the loop.The loop will continue until the list is empty.You can control how and when that condition arises.This level of control is often unnecessary, making the approach the looping construct of choice nine times out of ten. However, keep this technique in your bag of tricks in case you need to change the contents of your list in midstream.
33
34
Chapter 2
Working with Lists
2.12. Parsing Input Forms You want to use lists to help parse the values in an input form.
Technique Use the tag to iterate over a collection of values contained in a single input form field. These are the fruits you like: #fruit# You hate fruit! Which fruits do you like? #option#
Comments ColdFusion creates a list out of a form variable that has been defined multiple times on an input form. Consider, for example, the following URL submitted by a Web browser: http://localhost/colors_form.cfm?color=red&color=blue&color=green
Notice that the variable color has three values. Obviously, ColdFusion cannot create three unique variables with the same name, so it compensates by creating a single variable that is a list of three values. In other words, the value of the variable color is the string “red,blue,green”.
2.12.
Parsing Input Forms
The example shown in this technique demonstrates this concept by creating a small form that contains five check boxes with the same name.The template uses the looping technique to examine the contents of the submitted form. Notice that this example loops over two lists. It loops over the types of fruit that the user submitted in lines 6–8. However, the example also loops over a list of options (lines 16–19) to populate the input form.This is a nice way to save time typing while making the form more extensible.You can easily change the order and values of the options on the form by modifying the fruitOptions list.
35
3 Arrays
3.0.
Introduction
An array is a data type containing an ordered collection of variables. Items in an array are referred to as array elements and are referenced by their index (or numerical position) in the array. You use arrays when you have a collection of variables and need to store them in a defined order. Like lists (discussed in Chapter 2, “Working with Lists”), arrays support variable order—you can explicitly reference the value stored in a given position of the array. Although lists only store simple variables like strings and numbers, arrays can store complex data types, such as structures, queries, and even other arrays. If you need to store complex data types in a collection but do not need them in a defined order, you may want to look into using the ColdFusion data type structure, discussed in Chapter 4, “Structures.” This chapter shows you how to iterate over array element values, manipulate element values, and sort an array. It also explains how and when to use multidimensional arrays and how and when to use array aggregate functions.
3.1. Creating an Array You want to create a new array.
Technique Use the ArrayNew() function to create a new ColdFusion Array object.
38
Chapter 3
Arrays
Comments ColdFusion arrays are different than arrays in many other programming languages in that ColdFusion arrays are sized dynamically. A dynamically sized array is one that allows for expansion as elements are added—the programmer does not need know the size of the array when it is declared. Instead, ColdFusion sizes the array as the number of elements exceeds the size that ColdFusion initially appropriated. This dynamic sizing provides flexibility in programming but can also cause a performance hit—especially for large arrays, because ColdFusion essentially has to guess how large the array will eventually be. So if you know the maximum number of elements your array will contain, ColdFusion provides the ArrayResize() function to force a minimum size. ArrayResize() accepts two parameters, the array to resize and the minimum size to set that array. ColdFusion documentation suggests using the ArrayResize() function immediately following an array declaration that will contain more than 500 elements. Multidimensional arrays are covered later in this chapter—until then you’ll use only single dimensional arrays, created by passing a value of 1 to the ArrayNew() function. Note As a best practice, all arrays in this chapter begin with the letter a, as in aArrayName.
3.2. Adding an Element to an Array You want to add an element to an array.
Technique You add elements to an array by statically referencing the index of the element you want to insert, by using the ArrayAppend() function, or by using the ArrayPrepend() function.
3.3.
Displaying a Value in an Array
Comments After you’ve created an array, the natural next step is to populate its elements. (To create an array, see section 3.1, “Creating an Array.”) One way to set the index value of a given element in an array is to reference the element you want to populate by index and set its value explicitly.This code is an example of creating a new array named aPetSounds and setting the first and second element to the strings “You Still Believe In Me” and “That’s Not Me”, respectively, by reference. (Pet Sounds, of course, is an album by the Beach Boys—often considered their masterpiece.) Notice that ColdFusion uses 1-based numbering arrays—the first array element is in position 1. Many programming languages use 0-based numbering arrays, which place the first element in position 0. Another way to add an element to an array is to use either the ArrayAppend() or ArrayPrepend() function.This method of adding elements ensures you don’t place a value in an unintended index of the array. ArrayPrepend() will prepend your value to the array, making it the first element and pushing all other elements down an index.This is a useful function if you need to add an element to the beginning of an array, but aren’t worried about the other elements’ index values. For example, in the previous technique, Wouldn’t It Be Nice gains an index of 1, whereas You Still Believe In Me and That’s Not Me now have index values of 2 and 3, respectively (even though their index values were given explicitly). ArrayAppend() adds your element to the end of an array, making it the last element in the array, and leaving the other elements where they are. Use the ArrayAppend() function when you need to maintain the integrity of the array’s current index. Notice that Don’t Talk (Put Your Head On My Shoulder) is now a part of the petSounds array, but it has simply been “tacked on,” and has an index value of 4.This leaves the first three song titles’ index values untouched.
3.3. Displaying a Value in an Array You want to retrieve and display a value stored in an array.
Technique Use tags and reference the desired value by index to retrieve and display the value stored in a specific array element. Song 1: #aPetSounds[1]# Song 2: #aPetSounds[2]#
39
40
Chapter 3
Arrays
Song 3: #aPetSounds[3]# Song 4: #aPetSounds[4]#
Comments Executing this code produces the following output: Song Song Song Song
1: 2: 3: 4:
Wouldn’t It Be Nice You Still Believe In Me That’s Not Me Don’t Talk (Put Your Head On My Shoulder)
If you attempt to reference an element that does not exist in your array, ColdFusion throws an ArrayBoundException exception. Refer to Chapter 8, “Exception Handling,” for more information on exceptions in CFMX.
3.4. Looping over an Array You want to iterate over each element in an array.
Technique Use to iterate over each element in an array. Pet Sounds Track Listing Song #i#: #aPetSounds[i]#
Comments This example revisits the aPetSounds array and loops from 1 to the length of the array to extract and display the value of each element. Looping over an array to display its values ensures that you won’t reference an index that doesn’t exist.This code also shows that you can use ColdFusion expressions and variables to reference indexes within an array—in this case, you use the current index of the loop to retrieve the associated index in the array. Note This code introduces the ArrayLen() function. ArrayLen() accepts a single argument: the array in question. Similar to the Len() function, which counts the number of characters in a string, ArrayLen() returns the number of elements in an array.
3.6.
Sorting an Array
3.5. Manipulating Array Values You want to access or modify specific elements within an array.
Technique Manipulate elements in a populated array by iterating over the array and performing the desired function during each iteration of the loop.
Comments Arrays are used in Web applications to store ordered collections of related data. Naturally, as a user progresses through an application, data will change.Therefore, you need a way to manipulate the values of an array in order to perform functions on element values. Say you need to add the track number to each value in the aPetSounds array.You can do so by looping over the array values and manipulating the string to include the loop number, resulting in the desired value. Notice in the first cfloop statement that the value of the current element is referenced and a new value is set in the same line.This inline variable manipulation is acceptable in CFML.You also use the index variable i to insert the song number—a simple example of benefiting from the order functionality provided by the array data type. To display the new values with the track number prepended to the value, execute the following code: Pet Sounds Track Listing #aPetSounds[i]#
3.6. Sorting an Array You want to sort the elements of an array.
Technique Use the ArraySort() function to sort the elements of an array.
41
42
Chapter 3
Arrays
aAbcArray: element #i#: # aAbcArray[i]#
aAbcArray sorted with “text” attribute: element #i#: # aAbcArray[i]# aAbcArray sorted with “text” and “desc” attributes: element #i#: # aAbcArray[i]# aAbcArray sorted with “textnocase” attribute: element #i#: # aAbcArray[i]# aAbcArray sorted with “textnocase” and “desc” attributes: element #i#: # aAbcArray[i]#
3.6.
Sorting an Array
Comments The ArraySort() function sorts arrays numerically or alphabetically. It accepts two required arguments, the array to be sorted and the sort type, and one optional argument, sort order (which, if not provided, defaults to ascending). Using ArraySort(), the sort type argument can be numeric, text, or textnocase. If sort type is numeric, the array elements are sorted numerically in ascending or descending order based on the sort order argument. If no sort order is provided, ArraySort() uses ascending, the default. If sort type is text, the array elements are sorted alphabetically taking case into account. In text sorts, sort order ascending starts with uppercase A and ends with lowercase z, descending starts with lowercase z and ends with uppercase A. If sort type is textnocase, the array elements are sorted alphabetically without taking case into account.That is, if sort order is ascending, A/a precedes a B/b. If sort order is descending, a Z/z precedes a Y/y.Take a look at what happens when you execute the code in this technique: aAbcArray: element 1: element 2: element 3: element 4: element 5: element 6:
c B b A C a
aAbcArray sorted with “text” attribute: element 1: A element 2: B element 3: C element 4: a element 5: b element 6: c aAbcArray sorted with “text” and “desc” attributes: element 1: c element 2: b element 3: a element 4: C element 5: B element 6: A aAbcArray sorted with “textnocase” attribute: element 1: a element 2: A element 3: b
43
44
Chapter 3
Arrays
element 4: B element 5: c element 6: C aAbcArray sorted with “textnocase” and “desc” attributes: element 1: C element 2: c element 3: B element 4: b element 5: A element 6: a
3.7. Multidimensional Arrays You want to create an array with more than one dimension.
Technique Use ArrayNew(), passing in as a parameter the number of dimensions you require, to create a multidimensional array. = “Surfin’ Safari”> = “County Fair”> = “Ten Little Indians”>
= “Surfer Girl”> = “Catch a Wave”> = “The Surfer Moon”>
Comments A multidimensional array is an array of arrays rather than an array of single values. Until this point in the chapter, one-dimensional arrays have been covered, and the array elements have all been simple values—the name of a song or a letter of the alphabet. In a multidimensional array, you use the array elements to store other arrays.
3.8.
Creating Arrays with More Than Three Dimensions
ColdFusion allows you to define up to three dimensions in an array with a call to the ArrayNew() function. ArrayNew() takes one argument—1, 2, or 3—depending on
how many dimensions you need. This code is an example of creating a two-dimensional array. It continues using the Beach Boys as a model and uses a two-dimensional array to store album information in order of release. For this example, you use only the first three songs from each of their first three releases. If you want to display the values stored in the inner dimensions of an array, it is necessary first to get a handle on each element. Using cfloop is the best way to do so. Remember, you need exactly as many loops as you have dimensions in the array.
3.8. Creating Arrays with More Than Three Dimensions You want to create an array with more than three dimensions.
Technique Define multiple dimensions in an array by creating three dimensions at a time with ArrayNew(). #aDeepArray[1][1][1][1][1][1][1][1][1]#
Comments Although ArrayNew()lets you define only three dimensions, should the need arise you can bypass this constraint by setting any of the three dimension values to an array itself and repeat until you have the dimension depth you require.The code in this example places a string value in the lowly ninth dimension.
45
46
Chapter 3
Arrays
3.9. Array Aggregate Functions You want to perform aggregate functions on array elements.
Technique Use ColdFusion array aggregate functions to perform a function on all elements within an array. aArray aggregate functions Maximum Value: #ArrayMax(aArray)# Minimum Value: #ArrayMin(aArray)# Sum: #ArraySum(aArray)# Average: #ArrayAvg(aArray)#
Comments Aggregate functions are functions executed on multiple values—array aggregate functions are functions executed on each array element value. Table 3.1 defines the four functions available in ColdFusion MX. Table 3.1
maximum numeric value in array. smallest numeric value in array. numeric average of all values in array. numeric sum of all values in array.
Two exceptions of note when dealing with array aggregate functions are as follows: If there is a non-numeric value in an array passed into an aggregate function, ColdFusion throws a runtime exception. If the array passed into an aggregate function is empty, each of the functions returns a 0. n
n
3.10.
Array Utility Functions
Note that ColdFusionMX returns 0 when an empty array is passed into an array aggregate function. ColdFusion 5 returned infinity.
3.10.
Array Utility Functions
You want to perform utility functions on arrays.
Technique Use ColdFusion array utility functions.
Comments You have used a number of CFMX array utility functions in various techniques throughout this chapter.Table 3.2 defines each of the array utility functions, including ones you haven’t yet used. Don’t worry if you don’t understand them all yet—the more you work with arrays, the more you’ll find the need to reference this table. Table 3.2
ColdFusion Array Utility Functions
Function
Return Value
ArrayAppend(array, value)
Places value in the (array length plus 1) element of the specified array. Returns true if successful. Deletes all values from the specified array. Returns true if successful. Deletes the value at index in the specified array. All elements with an index greater than index will be offset by -1. Returns true if successful.Throws InvalidArrayIndexException if index is not a valid index for array. Inserts value at index of array.The index for elements with an index greater than index will be offset by 1. Returns true if successful. Throws the InvalidArrayIndexException exception if index is not a valid index for array. Creates an array of the specified dimension, which must be 1, 2, or 3. Places value in first element of specified the array. All indexes are offset by 1. Returns true if successful.
Resets array length to the specified size. Returns true if successful. Sets elements from index startIndex to endIndex to specified value in array. Returns true if successful. Sorts all elements in array by sortType (numeric, text, or textnocase) in specified order (asc or desc). If array contains anything other than simple values, ArraySort throws ArraySortSimpleValueException exception. If array contains non-numeric values and sortType is numeric, ArraySort throws ValueNotNumeric exception. Returns true if successful. Swaps the values at index1 and index2 of specified array. Throws ArraySwapRangeException exception if either index1 or index2 is an invalid index for array. Returns true if successful. Returns a list delimited by delimiter (a comma by default) containing the values in array.Throws ArrayNotOneDimensionException exception if array contains more than one dimension. Returns an array populated with the contents of list using delimiter to specify indexes. Empty values in list are ignored.
3.11. Array Information Functions You want to retrieve information about an array object.
Technique Use ColdFusion array information functions to retrieve information about an array object.
Comments Array Information functions are useful for gathering information about array objects. There are three ColdFusion array information functions, described in detail in Table 3.3.
3.11.
Table 3.3
Array Information Functions
ColdFusion Array Utility Functions
Function
Return Value
ArrayIsEmpty(array)
Determines whether the ColdFusion array object array is empty of elements. Returns true if empty. Returns the number of elements found in array. Determines whether array is a ColdFusion array object. If dimension is defined, determines whether the element contained in dimension is a ColdFusion array object. Returns true if the item is an array.
ArrayLen(array) IsArray(array [, dimension])
49
4 Structures
4.0.
Introduction
A structure is a complex ColdFusion data type containing key/value pairs of unsorted data. You use a structure to store data when you want to create an unordered collection of associated keys and values.Table 4.1 shows an example of how you might imagine the data type in the form of a table.This example uses the University of Alabama and their most recent NCAA Division 1 Football National Championship. Table 4.1 Representing a Structure Key
Value
GameDate
Jan 1, 1993 The University of Miami Gene Stallings
Opponent Coach
Those familiar with other programming languages might recognize this key/value pair concept as being an associative array. If so, you will be happy to know that you can refer to elements in a structure using traditional dot notation. If you aren’t familiar with associative arrays, no worries—this chapter defines and discusses their similarities. This chapter discusses the many advantages of using structures to store data.You learn how to create, populate, refer to, loop over, and sort structures.You also might learn a bit about the great football tradition of the University of Alabama Crimson Tide.
52
Chapter 4
Structures
4.1. Creating a Structure You want to create a new structure.
Technique Create a ColdFusion structure explicitly by using the StructNew() function or implicitly by setting a key/value pair in a new structure.
Comments There are two ways to create a structure in ColdFusion.The first is to use the StructNew() function.The first example in the technique shown here illustrates how to create a structure using this function.The other way to create a structure is to simply set a key/value pair inside the structure, thereby creating the structure and an element in that structure with a single line of code.The second example in the current technique uses only a single line of code to create a structure and to populate an element with the key someKey and the value “someValue”. Note As a best practice, all structures in this chapter begin with the letters st, as in stStructureName, except for those defined by ColdFusion, such as CGI and the named scopes.
4.2. Using Structure Information Functions You want to inspect a structure using ColdFusion structure information functions.
Technique Use IsStruct(), StructIsEmpty(), StructKeyExists(), and information about a structure.
StructKeyList()
is CGI a structure? #IsStruct(cgi)# is the CGI structure empty? #StructIsEmpty(cgi)# does the CGI structure contain a HTTP_USER_AGENT key?
to get
4.3.
Using Structure Management Functions
#StructKeyExists(cgi,”HTTP_USER_AGENT”)# What keys does the CGI structure contain? #StructkeyList(cgi)#
Comments Table 4.2 defines all four CFMX structure information functions and their return values. Table 4.2 CFMX Structure Information Functions Function
Return Value
IsStruct(variable)
Returns true if variable is a valid structure, false if it is not. Returns the number of keys in structure. Returns true if structure contains no elements, false if it contains one or more. Returns true if key is a valid key in structure, false if it is not.
Notice the code in the previous technique doesn’t include a call to StructNew(), nor does it create a value for the HTTP_USER_AGENT key. Actually, it doesn’t create any of the keys listed in the output of the StructKeyList() function.The reason? The CGI structure is available for manipulation because it is a CFMX named variable scope. All named variable scopes in CFMX are made available as structures. Note CFMX, unlike previous versions of ColdFusion, provides the Caller, Client, Server, and Variables scopes as structures.
4.3. Using Structure Management Functions You want to manage a structure using ColdFusion structure management functions.
Technique
Comments StructAppend() is one of nine CFMX structure management functions.Table 4.3 defines all nine CFMX structure management functions and describes their functionalities.
53
54
Chapter 4
Structures
Table 4.3 CFMX Structure Management Functions Function
Functionality
StructAppend(structureA, structureB[, overwrite])
Appends elements in structureA to structureB. If overwrite is false, the
value for a duplicate element is not copied. If its true, it is copied.The default is true. Returns true if the operation is successful; false if not. StructClear(structure) Removes all keys and values from structure. Returns true if the operation is successful; false if not. StructCopy(structure) Copies and returns structure with the same keys and values. Note that all elements are copied by value except nested structures, which are copied by reference. StructDelete(structure, key Deletes key and its corresponding value [, booleanReturn]) from structure. If booleanReturn is true, returns value boolean true if key exists and false if not. If booleanReturn is false, the return value is true. booleanReturn is false by default. StructFind(structure, key) Finds key in structure and returns its corresponding value. If key does not exist in structure, throws a runtime IllegalStructAccessException exception. StructInsert(structure, key, value ) Inserts new element into structure with [, overwrite] key and value. If overwrite is false, the value for a duplicate element is not copied. If its true, it is copied.The default is false. Returns true if the operation is successful; false if not. If key exists and overwrite is false, throws a StructInsertException exception. StructNew() Creates and returns a new, empty structure. StructSort(structure [, sortType Sorts structure or element structure of [ , order] ] [, structureReference based on structureReference]| sortType and order. Returns an array of structures populated with sorted key names. StructUpdate(structure, key, value) Updates structure and replaces value in element key to value. If key does not exist in structure, throws a runtime IllegalStructAccessException exception.
4.4.
Inserting Values into a Structure
The CFMX structure management functions are for managing structures inside your application. Be careful when manipulating the ColdFusion named scope structures, as you might experience unintended results. Note Do not use StructClear() to clean up your session variables, because this call will also remove the CFID and CFTOKEN variables, effectively destroying the session as opposed to clearing the session variables. Use StructDelete() if you truly want to clear the session variables. For more on sessions, see Chapter 7, “Application Flow.”
4.4. Inserting Values into a Structure You want to insert values into a structure.
Technique Use StructInsert() to insert data into a structure.
Comments After you create your structure, the natural next step is to populate it with data and otherwise manipulate the information stored therein.
55
56
Chapter 4
Structures
To simply place a key/value pair into a structure, you use the StructInsert() function. StructInsert() accepts four arguments—the structure into which you need to insert the element, the key, the value, and an optional Boolean fourth argument defining whether you want to overwrite a value should the key you are attempting to insert already exist. The previous technique shows an example of creating a structure of structures that store simple string data about the associated years’ undefeated teams. To illustrate inserting data into a structure, there’s a structure of structures representing the University of Alabama’s last two undefeated national championship teams.The Crimson Tide had two undefeated national championship teams in 13 years—one in 1979 and one in 1992. Remember though that there will be no inherent order in the parent structure, so you can’t retrieve the teams in order by year until you use StructSort(), discussed later in this chapter. If you need to store the data in order, you use the CFMX data type Arrays, discussed in detail in Chapter 3, “Arrays.”There is no guarantee as to the order of the elements in a structure—in fact, the very nature of a structure dictates that there is no order to its elements.
4.5. Updating Values in a Structure You want to update an existing value in a structure.
Technique Use StructUpdate() to update existing key/value pairs in a structure. Before Update: #StructFind(stTide1979,”Coach”)# After Update: #StructFind(stTide1979,”Coach”)#
Comments StructUpdate() accepts three arguments: the structure to update, the existing key in the structure, and the new value to be associated with that key.The example here
4.6.
Displaying the Value of an Element in a Structure Using the Key Name
updates the value of the key coach from Paul Bryant to Paul (Bear) Bryant. Calling StructUpdate() with a key that does not exist in the target structure results in an IllegalStructAccessException exception.
4.6. Displaying the Value of an Element in a Structure Using the Key Name You need to display the value of a structure element using the key name.
Technique Use StructFind() to reference the value of an element in a structure using the key name. Before Update: #StructFind(stTide1979,theKey)# After Update: #StructFind(stTide1979,theKey)#
Comments The technique in section 4.5 uses StructFind() to display the value of the Coach element in the stTide1979 structure.The technique in this section displays the same information but uses an expression to reference the desired value instead of the literal string name of the key. StructFind() is one of two ways to reference elements of a structure—section 4.7 describes the other.
57
58
Chapter 4
Structures
4.7. Using Dot Notation You want to use dot notation to manipulate the contents of a structure.
Technique Use dot notation or one of two other methods to insert values into and retrieve values from a structure. 2003 Coach: #stTide2003[“Coach”]# 2003 Projected Record: #StructFind(stTide2003,”Projected Record”)# 2003 Quarterbacks: #StructCount(stTide2003.stQuarterbacks)#
Comments Dot notation is the means of referring to a value by using the syntax structureName.keyName (if you are familiar with object oriented programming concepts, you probably recognize dot notation from object/property relationships).The technique in this section shows examples of all three ways to insert values into and retrieve values from a structure, including using dot notation. If you’ve programmed in ColdFusion before, chances are you’ve been using dot notation to reference session variables, URL variables, form variables, or other values from CFMX variable scopes. Remember—all named variable scopes in CFMX are available as structures, so everything you learn in this chapter not only pertains to structures you build for your own purposes, but also to the CFMX named scopes.
4.8.
Looping Over a Structure
The technique in this section also takes advantage of populating structure elements with other structures (this was covered earlier in the chapter). Note that to refer to elements of sub-structures, you simply provide the path to the parent structure and use your function or dot notation as usual.
4.8. Looping Over a Structure You want to iterate over the key/value pairs within a structure.
Technique Use StructKeyList() and cfloop to iterate over the elements in a structure. Famous Crimson Tide Football Players
Player Name
Position
#i#
#StructFind(stGreatTidePlayers,i)#
59
60
Chapter 4
Structures
Comments One of the more common tasks in dealing with structures is to loop over the structure to manipulate its elements. One important point to remember is that, because there is no order to elements in a structure, there is no way to predict the order in which the elements will appear in a loop. The technique in this section defines a structure that provides some information of just a few of the greatest Crimson Tide football players.You build the associative array by storing a player name in the key portion of the element and the position they played in the value portion. This example uses an associative array rather than a traditional structure. A traditional structure follows the object/property design defined earlier in the chapter. An associative array, by contrast, stores values in both the key and the value portion of a structure element. To iterate over the stGreatTidePlayers structure, you use the StructKeyList() function and loop over the returned list of keys. Each iteration of the list provides the current list item as an index, and you can use the current list item to reference the value of each element, because you know the item will be a key into the structure. Another way to loop over the structure is to pass the structure into the collection argument of cfloop.The technique code produces the same output should you change the cfloop line to read:
Notice that you use StructFind() instead of dot notation to reference the value stored in each element of the stGreatTidePlayers structure.This is because the key portion of the element, in this case, contains a space (Lee Roy Jordan). Be careful if you don’t know if the value of a key is valid within the dot notation syntax. CFMX will throw a ParseException exception when attempting to reference those keys.
4.9.
Using Structure Utility Functions
You want to manipulate a structure using ColdFusion structure utility functions.
Technique Use structure utility functions to manipulate the contents of a structure.
Comments StructKeyList() is one of six CFMX structure utility functions.Table 4.4 defines all
six of these functions and describes their functionalities.
4.10.
Copying Structures
Table 4.4 CFMX Structure Utility Functions Function
Functionality
Duplicate(structure)
Returns an exact copy of structure. All items are copied by value. Searches structure and its sub-collections for a key matching searchString. Returns an array of structures for each one found. Structure contains the elements owner, value, and path. If searchScope is set to all, all matching items are returned. If searchScope is set to one, only one item is returned.The default searchScope is one. Searches structure and its sub-collections for a value matching searchString. Returns an array of structures for each one found. Structure contains the elements owner, key, and path. If searchScope is set to all, all matching items are returned. If searchScope is set to one, only one item is returned.The default searchScope is one. Returns the item found in string structurePath. If no structure is found using structurePath, an empty one is created in structurePath and returned. Returns an array of keys found in structure.The order is unpredictable as structures do not impose order on their elements. Returns a list of keys found in structure. Delimiter is a comma by default unless otherwise specified.
The CFMX structure utility functions manipulate structures inside your application. Remember that all named variable scopes are provided as structures in CFMX, making these utility functions powerful when dealing with session, URL, form, and other scopes.
4.10. Copying Structures You want to copy the contents (deep or shallow) of a structure to another structure.
Technique Use Duplicate() to perform a deep copy of a structure. Use StructCopy() to perform a shallow copy.
61
62
Chapter 4
Structures
stBamaTradition - original structure SEC Championships: #stBamaTradition.SECChampionships# National Championships claimed by rivals: #stBamaTradition.stNationalChampionships.claimedByRivals# National Championships actual: #stBamaTradition.stNationalChampionships.actual#
stDeepCopyBamaTradition - created using Duplicate() SEC Championships: #stDeepCopyBamaTradition.SECChampionships# National Championships claimed by rivals: #stDeepCopyBamaTradition.stNationalChampionships.claimedByRivals# National Championships actual: #stDeepCopyBamaTradition.stNationalChampionships.actual#
stShallowCopyBamaTradition - created using StructCopy() SEC Championships: #stShallowCopyBamaTradition.SECChampionships# National Championships claimed by rivals: #stShallowCopyBamaTradition.stNationalChampionships.claimedByRivals# National Championships actual: #stShallowCopyBamaTradition.stNationalChampionships.actual#
Comments A deep copy copies all items, including sub-elements, by value. It returns an exact duplicate of the target structure. A shallow copy copies all items in the first dimension by value and all sub-elements by reference.
4.11.
Sorting Structures
Notice the output of the previous technique code.You created a first dimension element named SECChampionships.Then you performed both a deep copy and a shallow copy on the stBamaTradition structure before changing the value of SECChampionships. Notice the only structure that contains the updated value is the original stBamaTradition structure.This is because both the deep copy and shallow copy return the first dimension elements by value. The difference is in the items beneath the first dimension.The stNationalChampionships structure created to provide information about the Tide’s numerous championship years is copied by value into stDeepCopyBamaTradition using the Duplicate() function and copied by reference into stShallowCopyBamaTradition using the StructUpdate() function.This means that any changes to the stNationalChampionships structure will not appear in the stDeepCopyBamaTradition. After you update the values to reflect 2004 as a championship year, stDeepCopyBamaTradition still contains the value 12 for its actual key. stShallowCopyBamaTradition, however, contains the new correct value (13) because it does not contain a structure named stNationalChampionships. It instead contains a reference to the stNationalChampionships structure in stBamaTradition.
4.11. Sorting Structures You want to sort a structure.
Technique Use StructSort() to sort values in a structure.
School
Championships
63
64
Chapter 4
Structures
#i#
#stTotalChampionships[i]#
Comments The first rule of structures is that there is no order to their elements. It is obviously necessary for CFMX to provide programmers with a way to sort data stored in a structure. The StructSort() function enables you to do just that. StructSort() returns a sorted array of keys from the structure you provide to the function. It does not perform any action on the structure itself, so executing StructSort() does not change the elements of the structure in any way. It’s impossible to sort an object without order, right? StructSort() accepts one required and three optional arguments.These arguments are presented in Table 4.5. Table 4.5 StructSort()’s Arguments Argument
Description
Structure
The structure containing the keys you want returned sorted in specified order. text, textnocase, or numeric. text sorts with case sensitivity—lowercase values are grouped apart from uppercase values. textnocase disregards case in values. numeric sorts values numerically.The default is text. asc or desc. asc is for ascending sorts; desc is for descending sorts.The default is asc. The path to sub-element containing values required for the sort. Necessary for sorts based on sub-element values.
sortType
sortOrder structureReference
In the previous technique, the call to StructCopy() returned an array, which you set to the variable aTCArray.You then use the ArrayToList() function to create a list from the array values, which results in a sorted, comma-delimited list of keys for the structure. Now suppose you need to sort based on the value of a certain sub-element contained in the structure.The following code provides information about the four great coaches who won national championships at Alabama.The keys of the first dimension of the structure are the coaches’ names.The second dimension stores numerical data about the
4.11.
Sorting Structures
number of championships won and the most recent winning year for each coach. It then sorts the keys to the first dimension based on the values stored in the second. In order of most championships
Coach
Number of Championships Won
#i#
#stChampionships[i].count#
In order of most recent championship
65
66
Chapter 4
Structures
Coach
Last Championship Won
#i#
#stChampionships[i].recent#
Remember that StructSort() returns an array of keys to the structure passed in the first argument.You need to reference the struct again to retrieve the value associated with that key.
5 Queries
5.0.
Introduction
ColdFusion’s capability to connect to a data source and retrieve data is possibly the most widely used functionality in the language. Most developers are familiar with the query object through its use in the process required to connect to and retrieve data from a data source. In addition to the base query functionality, ColdFusion provides developers the capability to do the following: n
n
n
n
Manually create query objects for use in Web applications Query the recordset retrieved from a previous query (thus creating a query of queries) Manage the data contained within a query recordset Cache queries and limit the number of calls to the database
This chapter discusses and provides examples of all of these features and more.You’ll learn that the ColdFusion query object is a powerful, useful construct and can be used in many ways.
5.1. Querying a Database You want to retrieve values from a database.
Technique Use the ColdFusion tag to connect to a database and return a recordset in the form of a ColdFusion query object.
68
Chapter 5
Queries
SELECT UserName, PassWord FROM Users is qGetUsers a query object? #isQuery(qGetUsers)#
Comments This technique shows a simple query against the Users table of the cfcookbook data source (the cfcookbook schema is defined in detail in Chapter 13, “User Authentication and Authorization”). Executing this code example presents a simple YES to the users— the result of the isQuery() function call. This code example uses only those parameters required to execute a query against a data source using the tag: the data source and name (if you are performing a query of queries, as is discussed later in this chapter, the datasource parameter is not used).The ColdFusion tag accepts two required and nine optional parameters.Table 5.1 describes each of these parameters and describes their functions. Table 5.1 cfquery Parameters Parameter
Function
Datasource
Required. Name of the ColdFusion data source for the query. Required. ColdFusion executes the query and returns a query object with the name specified in this parameter. This parameter pertains only to Oracle data sources and defines the number of records to return from the database at one time. Must be a valid ColdFusion date value. If query caching is enabled in the ColdFusion Administrator and this parameter value is less than the date of the original query, ColdFusion will return the cached recordset. Must be a valid ColdFusion time span (created with CreateTimeSpan() function). If query caching is enabled in the ColdFusion Administrator and the original query date falls within the specified time span, ColdFusion will return the cached recordset. Used in a query of queries to specify that the target dbType is a valid ColdFusion query object. Not used if the query target is a database. If debugging is enabled in the ColdFusion Administrator and Database Activity is disabled, a value of true overrides the Database Activity setting. Also, omitting the equals sign and the true value implies true. Maximum number of rows to return in the recordset. Password for the data source. Maximum time permitted to execute each operation performed in a query. Username of the data source.
Name blockFactor cachedAfter
cachedWithin
dbType Debug
maxRows Password Timeout Username
5.2.
Programmatically Creating Queries
The following attributes of the tag are deprecated as of ColdFusion MX: connectString, dbName, dbServer, provider, providerDSN, and sql. Using them in a ColdFusion MX environment may cause errors or otherwise unexpected results. Note As a best practice, all queries in this chapter begin with the letter q, as in qQueryName.
5.2. Programmatically Creating Queries You want to manually create a new query object.
Technique Use the QueryNew() function to programmatically create a ColdFusion query object. Use the QueryAddRow() and QuerySetCell() functions to programmatically add values to your query object. #firstName# #lastName#, #age# years old Total Records: #qSimpleQuery.recordCount#
Comments The capability to create ColdFusion query objects programmatically allows developers to take advantage of query-specific features, like the recordCount, currentRow, and columnList variables. As you’ll learn later in the chapter, a query object can also be the target of a execution—enabling you to create a query of a query. The steps to create a query object are as follows:
69
70
Chapter 5
n
n
n
Queries
Create the query object using the QueryNew() function. Create one or more rows in the query object using the QueryAddRow() function. Add data to the query object using the QuerySetCell() function.
The QueryNew() function accepts a single required parameter, which is a list of columns to create in the query object.The previous technique created a query object named simpleQuery with the columns firstName and lastName. ColdFusion requires a column list to create a new query, even if it is empty. The QueryAddRow() function accepts one required and one optional parameter.The required parameter is the name of the query to which you need to add a row.The second and optional parameter is the integer number of rows you need to add. If you do not specify a number, the function adds only one.The example here shows only a single row and accepts the default value of 1. Note that the QueryAddColumn() function accepts three parameters, all required. The first is the name of the query to which you need to add the column.The second is the name of the new column.The third is an array of values.The values in the array are copied to the new column in the query in the order in which they appear in the array. If the query contains more rows than the array, the query will pad the column with empty values.
5.3. Displaying Query Results You want to display the results of a query in a Web page.
Technique Display the values stored in a query using , , or by explicit reference. Use cfoutput to display query values: #firstName# #lastName#
5.4.
Using Query Variables
Use cfloop to display query values: #firstName# #lastName#
Use an explicit reference to display query values: #qPresidents.firstName[i]# #qPresidents.lastName[i]#
Comments This technique shows an example of each of the three ways to display the values stored in a query object—by using , by using , and by explicitly referencing the value by column and row index. To use , you must pass the name of the query into the query attribute of the tag. Doing so causes the CFML inside the to execute once for every record in the query, much like the behavior of a statement. Using with the query attribute is very similar to using with the query attribute.The only difference is that there is no . If you want to evaluate ColdFusion variables within the loop, you need to make sure your statements are contained within tags. The third way to display the values stored in a query is to do so by explicitly referencing the value by column and by row index.The syntax is queryName.columnName[rowIndex], where queryName is the name of your query, columnName is the name of the column containing the variable you need to display, and rowIndex is the cardinal-based index of the row containing the value you need to display.
5.4. Using Query Variables You want to inspect a query using ColdFusion query variables.
Technique ColdFusion provides a number of variables along with the query scope to help you better understand the object. Reference the variables like you do variables of any scope to inspect their values.
71
72
Chapter 5
Queries
SELECT UserName, PassWord FROM Users Query Information record count: #qGetUsers.recordCount# column list: #qGetUsers.columnList# current row: #qGetUsers.currentRow# execution time: #cfquery.executionTime#
Comments The four ColdFusion Query Variables are recordCount, columnList, currentRow, and executionTime, and they are described as follows: recordCount provides the integer number of total records available in a query. columnList provides the list of column names present in the query. Note that the column names returned in the variable columnList are in alphabetical order rather than in the order provided in the SQL statement. currentRow provides the index of the current row.This is especially useful when executing cfloop statements. executionTime provides the cumulative number of seconds spent processing the query. Note that the syntax for retrieving the executionTime value is cfquery.executionTime rather than queryName.executionTime. n
n
n
n
The following code shows an example of inspecting the value of currentRow to interlace the background colors of the rows in a table. It uses columnList to display column headings and to retrieve query values. It also shows the query execution time and the total number of rows contained in the query. SELECT FirstName, LastName, City, State FROM Users
User Information
5.5.
Creating Queries of Queries
#i#
#evaluate(i)#
73
74
Chapter 5
Queries
SELECT FirstName, LastName FROM qGetUsers WHERE State = ‘NC’ NC users #qGetNCUsers.FirstName# #qGetNCUsers.LastName#
SELECT FirstName, LastName FROM qGetUsers WHERE State ‘NC’ Other users #qGetOtherUsers.FirstName# #qGetOtherUsers.LastName#
Comments The query of queries (sometimes called an in-memory query) is a powerful ColdFusion feature. It can significantly improve performance if you find the need to select data from the same table more than once. Using a query of queries, you need only a single call to the database, as shown in the previous technique. Executing a call returns a dataset, which in many ways is similar to a database table—a recordset contains data structured as a virtual table with rows and named columns.This similarity is exploited in the query of queries’ functionality. ColdFusion treats the recordset as a database table against which you can execute SQL statements to retrieve data. Without a query of queries, the technique code would require two database calls to extract two separate recordsets with the desired data—one to retrieve users from NC and one to retrieve users not from NC. By using a query of queries, you can pull all the users in one database call and then query the returned recordset using the appropriate WHERE clauses. A query of queries is also beneficial in conjunction with cached queries.You can display the results of a single cached query in any number of ways across multiple templates using the cached recordset as a virtual table. Note also that you are not limited to database-returned recordsets when using a query of queries.You can use any valid ColdFusion recordset as the input.The result of a call, for example, is valid for input into a query of queries.
5.6.
Converting a Query Column to a List
5.6. Converting a Query Column to a List You want to extract all query values for a specific column and store them in a list.
Technique Use the ValueList() or QuotedValueList() functions to return a list of all values stored in a specific query column. SELECT FirstName FROM Users All UserNames #ValueList(qGetUsers.FirstName)#
SELECT Name FROM Employees Where Name IN (#quotedValueList(qGetUsers.FirstName)#) Shared First Names #Name#
Comments The ValueList() and QuotedValueList() functions are used to create a list from a specific column in a query. ValueList() accepts one required and one optional argument.The required argument is the name of the query you need to transform into a list object.The optional argument is the delimiter to use for the list. If you do not provide a delimiter, a comma is used as the default. QuotedValueList() also creates a list from a query column but qualifies the values with single quotes.The function otherwise behaves exactly like ValueList(), with the same required and optional arguments.
75
76
Chapter 5
Queries
QuotedValueList() is especially useful in conjunction with a query—you can use the quoted list as the IN clause of a SQL statement, as is shown in the previous technique. For more information on ColdFusion lists, see Chapter 2, “Working with Lists.”
5.7. Caching a Query You want to use the cached result of a previous execution.
Technique Use the cachedAfter or cachedWithin parameters of to use cached results if they exist. SELECT FirstName, LastName, City, State FROM Users ORDER BY LastName Users #LastName#, #FirstName# - #City#, #State# Execution Time: #cfquery.ExecutionTime#
SELECT FirstName, LastName, City, State FROM Users ORDER BY LastName Users
Comments Query caching is a great tool for improving Web application performance.The fewer the number of calls you make to the database, the faster your application. You can control the number of queries ColdFusion will cache by changing the default setting. Up to 100 queries are cached by default.The stack will eliminate the oldest query if the threshold is reached. In order to use a cached query, the following stipulations must be met: Both queries must have the same name value Both queries must have the same datasource value Both queries must use the same SQL statement Both queries must have the same username, if applicable Both queries must have the same password, if applicable The cached query must have been executed within the supplied time span if cachedWithin parameter is provided The cached query must have been executed since the supplied date if the cachedAfter parameter is provided n
n
n
n
n
n
n
The technique code shows an example of using cached queries with cachedAfter and cachedWithin.The first execution of the technique code should show a value for the execution time for both queries. An immediate refresh of the page will show the same data, but with execution times of 0, because ColdFusion used the cached query results rather than executing a new call to the database.
77
6 Dates and Times
6.0.
Introduction
A date is a data type that represents an instant. A date is really both a date and a time— all date objects represent both values. ColdFusion dates are accurate to the nearest second. Dates can be formatted in a number of ways.The same date object can be formatted as a date string, such as “05/16/67” in one case, and then formatted as a time, such as “7:08 a.m.”, in another. It is up to the developer to determine how a date should be rendered.There are some standard formats (called masks) that can help you present a date in the appropriate format. In one instance you may simply display a date as a string. In another, you may need to format the date as an ODBC date for a database query. In another case, the date may need formatting as an HTTP time string for setting cookie expiration. This chapter explores ColdFusion date/time support, including creating, formatting, displaying, and performing computations on date and time objects.
6.1. Creating a Date, Time, or DateTime Object You want to create a ColdFusion Date, Time, or DateTime object.
Technique Use the appropriate ColdFusion date and time create function to create a ColdFusion Date, Time, or DateTime object.
80
Chapter 6
Dates and Times
Comments This technique is a simple example of creating three date objects representing a Date, a Time, and a DateTime.These date objects can now be used in any ColdFusion functions that expect a date object as a parameter. The parameters passed to each function used in the technique are presented in Table 6.1. Table 6.1 Date and Time Create Parameters Function
Parameters
CreateDate(year,month,day)
year (0-9999),month (1-12),day (1-31). Note the time portion of the returned date object is set to 00:00:00.
CreateTime(hour,minute,second)
hour (0-23), minute (0-59), second (0-59). Note that the date portion of the returned date object is set to 1899-12-30 (December 30,
CreateDateTime
year (0-9999),month (1-12),day (1-31), hour (0-23), minute (0-59), second (0-59).
1899).
Notice that when you output the values created in the technique without a mask, the display is a timestamp—essentially unreadable unless your users are expecting it.The following code shows the result of displaying the three date objects created as raw date objects, without using a formatting mask. mycreatedate = {ts ‘2002-05-22 00:00:00’} mycreatetime = {ts ‘1899-12-30 08:12:30’} mycreatedatetime = {ts ‘2002-05-22 08:12:30’}
So the primary use of these create functions is to create a date object representing a point in time.These functions are not for display purposes.
6.2. Formatting Dates You want to format a date for user-friendly display.
Technique Use the ColdFusionDateFormat() function with the appropriate mask to format a date object for display. #DateFormat(CreateDate(2002,11,17),”mmmm d, yyyy”)#
6.2.
Formatting Dates
Comments The DateFormat() function is essential when using ColdFusion date objects. DateFormat() accepts two parameters: the date object (or string representation of one) to be formatted and the mask with which to format that date object.The mask parameter is a string representing the format to display.Table 6.2 describes available characters to create masks. Table 6.2 DateFormat Mask Values Date Part
Character Masks and Examples (formatting September 05,2002 6:06:05 PM)
ColdFusion also supplies preformatted masks to display date values.These are listed in Table 6.3.
81
82
Chapter 6
Dates and Times
Table 6.3 DateFormat Mask Values Mask Name
Example
short
11/17/02 Nov 17, 2002 November 17, 2002 Sunday, November 17, 2002
medium long full
To display today’s date, use the ColdFusion function Now() as the date parameter for the DateFormat() function. Now() returns a date object representing the present moment in time, from the current year to the current second.The following example uses DateFormat() to place different formatting masks on the returned value of Now(). Run this code on your machine and notice the different displays.
Mask
Result
”full”
#DateFormat(Now(),”full”)#
”mm - dd - yy”
#DateFormat(Now(),”mm - dd - yy”)#
”d mmm”
#DateFormat(Now(),”d mmm”)#
6.3. Comparing Dates You want to determine whether a date is greater than, less than, or equal to another date.
Technique Use the ColdFusion DateCompare() function to compare two date objects.
6.4.
Determining Date Differences
#DateCompare(Now(),birthday)#
Comments The ColdFusion DateCompare() function accepts two required parameters and one optional parameter.The two required parameters are date objects, whereas the optional parameter is the precision you want to use for the comparison. DateCompare() returns one of three values: –1, 0, or 1. A –1 return value means the first date parameter is less than the second. A 0 return value means the two dates are identical. A 1 return value means the first date parameter is greater than the second. Executing the code in the previous technique will return a 1 because the date returned from the call to the Now() function is greater than the date value for the variable named birthday. You can also alter the precision with which DateCompare() compares two dates by providing a third parameter.This third parameter is the shorthand value for the date part you want to compare—instructing DateCompare() to be precise only to the supplied date part.Table 6.4 describes the values acceptable for this precision parameter. Table 6.4 DateCompare Precision Values Precision Value
Description
yyyy
Year Month Day Hour Minute Second
m d h n s
Altering the precision used in DateCompare() is useful for comparing two date objects when, for example, you only need to know that they represent dates within the same minute or within the same hour.
6.4. Determining Date Differences You want to determine the difference in time between two date objects.
Technique Use the ColdFusion DateDiff() function to determine the difference in time between two date objects.
83
84
Chapter 6
Dates and Times
#DateDiff(“s”,birthday,Now())#
Comments The ColdFusion function DateDiff() compares two dates and returns the number of selected date parts between the two.The previous technique returns the difference in seconds between the return value of the Now() function call and the value for the date object variable birthday. Executing this code displays a number value of nearly 800 million.Table 6.5 describes the accepted values for the date part parameter. Table 6.5 DateDiff Date Part Parameter Values Date Part Value
Description
s
Second Minute Hour Week Weekday Day Day of Year Month Quarter Year
n h w ww d y m q yyyy
6.5. Formatting Times You want to format a time for user-friendly display.
Technique Use the ColdFusion TimeFormat() function with the appropriate mask to format a date object for display. #TimeFormat(now(), “h:mm tt”)#
Comments Use the ColdFusion TimeFormat() function with the appropriate mask to format the time portion of a date object for display. TimeFormat() accepts two parameters: the
6.6.
Defining Time Spans
date object (or a string representation of one) containing the time to be formatted and the mask with which to format that time.The mask parameter is a string representing the format to display.Table 6.6 describes available characters to create masks. Table 6.6 TimeFormat Mask Values Time Part
Character Masks and Examples (formatting 6:05:04 PM Eastern Standard)
Hour
h: 6 hh: 06 H: 18 HH: 18 (capital H used for 24 hour time) m: 5 mm: 05 s: 4 ss: 04 t: P tt: PM
Minute Second Suffix
ColdFusion also supplies preformatted masks to display time values.These are listed in Table 6.7. Table 6.7 TimeFormat Mask Values Mask Name
Example
Short
6:05 PM 6:05:04 AM 6:05:04 PM EDT 6:05:04 PM EDT
Medium Long Full
6.6. Defining Time Spans You want to define a date or time period.
Technique Use the ColdFusion function CreateTimeSpan() to define a date or time period.
85
86
Chapter 6
Dates and Times
Comments The CreateTimeSpan() function is useful in three ways. First, it is used as an attribute value in the tag for defining session and application timeout (see Chapter 7, “Application Flow,” for details on ColdFusion applications). Second, it used as an attribute in tags in conjunction with query caching to define the time period for which a cached query is valid (see Chapter 5, “Queries,” for more detail on ColdFusion queries).Third, it is used to subtract from or add to DateTime objects. To add or subtract time to an existing date object, use CreateTimeSpan() and simple arithmetic on an existing date. See the following code; it shows today’s, yesterday’s, and tomorrow’s date using only the Now() function and a time span object representing a 24-hour period. Today is #DateFormat(today,”dddd, mmmm d”)# Yesterday was #DateFormat(yesterday,”dddd, mmmm d”)# Tomorrow is #DateFormat(tomorrow,”dddd, mmmm d”)#
6.7. Using Date Information Functions You want to inspect a date object for specific information.
Technique Use one of the many ColdFusion information functions to inspect a date object for specific information. #isLeapYear(Year(Now()))#
Comments ColdFusion provides a number of date information functions useful for inspecting date contents and for extracting information from date objects and portions of date objects. The previous technique uses two of these said functions to determine whether the current year is a leap year. If you execute this code during a leap year, the code will display a value of YES, otherwise it will display NO. Table 6.8 lists the ColdFusion information functions and their return values.
6.7.
Using Date Information Functions
Table 6.8 ColdFusion Date Information Functions Function
Return Value
DayOfYear(dateObject)
The numeric day of the year contained in dateObject. The number of days of the year contained in dateObject. The number relating the first day of the month in dateObject to the beginning of the year contained in dateObject. The number of days of the month contained in dateObject. Integer must be in the range 1-12. Returns the month as a string corresponding to the supplied integer. The numeric day of the week contained in dateObject. Sunday is a 1; Saturday a 7. Integer must be in the range 1-7. Returns the day of the week as a string corresponding to the supplied integer. YES if year integer is a leap year; NO if it is not. The year contained in dateObject. The numeric quarter of the year contained in dateObject (1-4). The numeric month contained in dateObject. January is a 1; December is a 12. The number relating the week in dateObject to the beginning of the year contained in dateObject. The numeric day of the month contained in dateObject. The numeric hour contained in dateObject, returned as a 24-hour value. The numeric minute contained in dateObject. The numeric second contained in dateObject.
6.8. Managing Dates and Times in Different Locales You want to format ColdFusion date objects in a locale-specific manner.
Technique Use ColdFusion locale-specifc date functions to manage dates over different locales. Format for Locale #GetLocale()# is: #LSDateFormat(Now(),”long”)# Format for Italian (Standard) is: #LSDateFormat(Now(),”long”)#
Comments Dates are closely linked to the locale. A locale setting tells ColdFusion which part of the world is using the application. Learning to take advantage of locale settings is a powerful skill for developers, especially in today’s’ 24-hour e-business environment. ColdFusion’s default locale is the same as the default local of the underlying Java Virtual Machine. Locales allow ColdFusion to format dates according to a variety of pre-defined locations, so you don’t need to know the various formats of those locations. ColdFusion provides rich functionality for managing date objects in a locale-specific manner. Executing the code in the previous technique will display the current time formatted for your default locale. It then changes the default locale for your client (which will last the extent of your session) to Italian (Standard). Displaying the date, using the same mask for the LSDateFormat() function, produces a new result—this time formatted for the Italian (Standard) locale. Note ColdFusion can manage dates as locale-specific as long as the locale needed is defined on the ColdFusionMX Server. The Server.ColdFusion.SupportedLocales variable contains a commadelimited list of supported locales for the current server. Attempting to display date and time values in locales not defined on the server generates a runtime critical CFLocaleMgrException exception.
There is also a similar formatting function for displaying time values per locale, called LSTimeFormat(). Change the code in the previous technique to use LSTimeFormat() instead of LSDateFormat() to see the time formatted for different locales.
II Controlling Application Flow 7
Application Flow
8
Exception Handling
7 Application Flow
7.0.
Introduction
A ColdFusion application is a group of ColdFusion templates associated to perform specific functions. Most ColdFusion Web sites are ColdFusion applications. Anything from a simple form presentation and data-capture mechanism to a full-blown back office intranet system can be considered a ColdFusion application. A ColdFusion application consists of an Application.cfm page and shared variable scopes for the ColdFusion templates associated with the application. Applications allow template access to the session scope, the client scope, and the application scope. This chapter defines how to create and manage an application and also describes the various scopes available within an application.
7.1. Creating a ColdFusion Application You want to create a ColdFusion application.
Technique Use the tag to create a ColdFusion application.
Comments The only requirement to create a ColdFusion application is the presence of the tag.This tag is usually placed in a file named Application.cfm located in the root directory of your application.The Application.cfm file is useful because if ColdFusion finds this file in the directory or any parent directories up to the
92
Chapter 7
Application Flow
Web root, code inside the file will be executed before any logic in the requested page. For that reason, it’s typical to set global variables in what is called the application scope so that they will always be available to the templates comprising the application. The tag allows you to associate ColdFusion templates for the purposes of defining a ColdFusion application.There are no required attributes for the tag, although there are numerous optional ones.Table 7.1 defines these attributes and describes their purposes. Table 7.1 cfapplication Optional Attributes Attribute
Description
applicationTimeout
A timespan value that defines the lifetime of variables in the application scope.The default is set in the ColdFusion Administrator. Defines whether the client variable scope exists for the application. Accepted values are Yes and No. Default is No. If Client scope variables are used, this variable defines the storage mechanism for those values. Accepted values are cookie, registry, or the name of any valid ColdFusion data source configured to store client variables. Client storage is discussed in detail later in this chapter. Default is registry. The string name of your ColdFusion application. If you choose to use the application or session variable scopes, this attribute is required. Defines whether the session variable scope exists for the application. Accepted values are Yes and No. Default is No. A timespan value that defines the lifetime of variables in the session scope.The default is set in the ColdFusion Administrator. Defines whether ColdFusion sends cookies to the client machine containing client identifiers for the application. Default is Yes. Sets domain-level client identifiers, used primarily for applications running in a clustered environment. Accepted values are Yes and No. Default is No.
When ColdFusion executes any .CFM template, it will look up the directory tree for the presence of an Application.cfm file and should it find one, it will execute the code in that file before processing the requested template.The tag is usually the first line of code in the Application.cfm file.The tag is used to define the type of application the requested file belongs to. Note Users are not allowed to browse directly to pages named Application.cfm. If they attempt to do so, ColdFusion throws a ReservedTemplateException exception.
7.1.
Creating a ColdFusion Application
The applicationTimeout attribute defines the lifetime of variables in the application scope. If the application scope is used, the name attribute of the tag is required.The value of the applicationTimeout attribute is a valid ColdFusion timespan usually created with a call to the CreateTimeSpan() function. For more on the CreateTimeSpan() function, see Chapter 6, “Dates and Times.”The following line of code defines a ColdFusion application with an application scope lifetime of 2 days and 12 hours:
You can also omit the applicationTimeout attribute, thereby accepting the default value for the parameter.The default for this value is a server-wide setting controlled by the ColdFusion Administrator.To change this setting, log into your ColdFusion Administrator and browse to the Memory Variables page. Note that from this page you can also disable the use of the application variable scope, as well as define a maximum timeout value. If you need to use the client variable scope, you need to set the value for clientManagement to Yes and also define a storage mechanism for the client variables.You also need to decide on a value for setClientCookies. If set to Yes, setClientCookies instructs ColdFusion to store the client identifier as a cookie on the client machine. Note that users can reject acceptance for cookies, so setClientCookies should be used with caution if your application is not used in a controlled client environment. Storage strategies for client variables are discussed later in the chapter. Likewise, if you need to use the session variable scope, you need to set the value for sessionManagement to Yes.The ColdFusion administrator allows you the option to choose ColdFusion Session Management or J2EE Session Management. If you use ColdFusion Session Management, session variables use the same client identifier as ColdFusion client variables (CFID and CFTOKEN) and are not available to any Java Server Pages (JSPs) or Java servlets you may access inside of your application. If you use J2EE session management, your client identifier is available through a variable named jSessionId and variables inside the session scope are made available to any JSPs you may access inside of your application. Client and session variable scopes effectively store information about a single client inside a single application.The best practice is to use the session variable scope to store single-session specific variables and to use the client variable scope to store values that you need to access over a number of different client sessions. For example, a good place to store shopping cart-related values is in the client scope, because you’ll likely want the application to recall the contents of a user’s shopping cart over a number of client sessions.
93
94
Chapter 7
Application Flow
7.2. Using the Application Variable Scope You want to initialize application-wide settings and variables before each page request.
Technique Use and the application prefix inside Application.cfm to initialize variables in the application scope.
Comments This technique initializes three application scope variables to be executed before each .CFM page request. One common variable set in database-driven Web sites is the name of the primary data source for the application. Using the code in the technique allows developers responsible for individual page development to access the primary database without needing to know the name, username, or password necessary for access.This way, the developer responsible for managing the ColdFusion data source can change the username or password, and even change the name of the DSN without worrying about seeking out each call to the database inside the application and changing the connection information.Without setting the DSN name, username, and password in the application page, each query to the database might look like: Select ...
But if the developer responsible for managing the entire ColdFusion application defines the values for the DSN name, username, and password inside the application scope, developers responsible for individual template development can simply use the application variables for the necessary values, thereby allowing the global change of these values in a single setting, like so: Select ...
7.3.
Implementing Session Management
7.3. Implementing Session Management You want to use ColdFusion Session Management in your application.
Technique Use the session prefix to manage variables in the session scope.
Comments This technique determines whether the session variable named todaysDate exists, and if it does not, creates it and sets it to the value returned from a call to the Now() function. Now() returns a ColdFusion Datetime value equal to the current date and time on the application server. For more information about the Now() function, refer back to Chapter 6. In order to use the session scope you need to first add the sessionManagement attribute to your tag and set it to Yes. After you’ve done so, you can manage variables stored in the session scope. If you are using ColdFusion Session Management, an initial page request from a client sets four variables immediately in the session scope for that user: CFID, CFTOKEN, sessionId, and urltoken. Note The variables set by ColdFusion in the session scope are writable, just as the variables placed there by a developer are. Changing the variables set by ColdFusion in the session scope can produce unexpected results and is not recommended.
The session.CFID and session.CFTOKEN will be the same value as the client.CFID and client.CFTOKEN if you are also using Client Management.These two variables represent the unique client identifier ColdFusion will use to retrieve client-specific variables in the session and client scopes.The session.sessionId will be a concatenated value of the application name, the CFID, and the CFTOKEN.The urltoken will be a URL-formatted value of the CFID and CFTOKEN. It is a good idea to pass this urltoken between page requests to ensure session integrity.The following code shows how to pass the CFID and CFTOKEN identifiers across URLs: link
95
96
Chapter 7
Application Flow
This code displays as the following link in the HTML sent to the client browser (of course, the values for CFID and CFTOKEN are specific to each application and each user): link
Passing this client identifier along with page requests allows ColdFusion to reference the individual client’s session scope variables. The session scope, like the application scope, is stored in memory on the application server. For high load applications, Client Management with an optimized storage mechanism may be a better idea for storing client specific data. Note The session scope should be used for values that you want to exist only for the current session. If you need to set a variable whose lifetime should exist over multiple sessions, use the client scope instead.
7.4. Implementing Client Management You want to use ColdFusion Client Management in your application.
Technique Use the client prefix to manage variables in the client scope.
Comments This technique determines whether the client variable named navigationPreference exists, and if it does not, creates it and sets it to the value for the application variable defaultNavigationPreference. In order to use the client scope, you first need to add the clientManagement attribute to your tag and set it to Yes.You can also set the clientStorage value to define the storage mechanism for the client scope (client scope storage is discussed later in this chapter). After you’ve done so, you can manage variables stored in the client scope. An initial page request from a client immediately initializes six variables in the client scope for that user: CFID, CFTOKEN, hitCount, lastVisit, timeCreated, and urltoken.
7.5.
Storing Client State Using the Registry
Note The variables set by ColdFusion in the client scope are writable, just as the variables placed there by a developer are. Changing the variables set by ColdFusion in the client scope can produce unexpected results and is not recommended.
The client.CFID and client.CFTOKEN will be the same value as the session.CFID and session.CFTOKEN if you are also using Session Management. These two variables represent the unique client identifier that ColdFusion will use to retrieve client-specific variables in the client and session scope. The hitCount value is an integer defining the number of times the client has requested a page within your application.The lastVisit value is a ColdFusion DateTime value equal to the date and time of the last page request within this application from this client.The timeCreated value is a ColdFusion DateTime value equal to the date and time the client store was created for this user in this application. Tip The client scope should be used for values that you want to exist across user sessions. If you need to set a variable whose lifetime should exist only for the extent of the current user session, use the session scope instead.
One primary difference between the client scope and the session scope is that client scope can only store simple values, whereas the session scope can include complex values. A simple value is one that can be converted into string, which includes variables of type string, boolean, datetime, and number.Variables such as structures and arrays cannot be stored in the client scope in their native form.You must store structures and arrays (or other complex data types) in the client scope, serialize the complex object to a wddx string, and then store that value instead. For more on WDDX, see Chapter 21, “WDDX.”
7.5. Storing Client State Using the Registry You want to store client-state information in the application server registry.
Technique Set the attribute clientStorage to registry to store client state data in the application server registry:
97
98
Chapter 7
Application Flow
Comments This technique creates a ColdFusion application, initializes the client variable scope, and instructs ColdFusion to use the application server system registry to store client scope information. ColdFusion installs with registry client storage as the default, so unless changes have been made in the ColdFusion administrator, you can omit the clientStorage attribute and accept the registry as the default setting. If your ColdFusion Application Server is on a UNIX machine, registry storage is not an option. Also note that you cannot use the registry storage option in a clustered application environment. Although registry client storage is the default setting, there are many disadvantages. The primary disadvantage is that registry storage does not scale well for many clients. When using registry storage, each client is provided a singular registry entry. ColdFusion stores these entries in the registry locationHKEY_LOCAL_MACHINE\SOFTWARE\ Macromedia\ColdFusion\CurrentVersion\Clients.You will have as many entries in the registry as you have clients who have accessed applications on your application server.
7.6. Storing Client State Using Cookies You want to store client state information in the application server registry.
Technique Set the attribute clientStorage to cookie to store client state data in client cookies.
Comments This technique creates a ColdFusion application, initializes the client variable scope, and instructs ColdFusion to use cookies to store client scope information. Cookies are encrypted text files sent to the client machine typically used to store small bits of information, such as client identifiers. Cookies are not human readable and are only accessible by the domain that created them. Storing client scope data in cookies provides the attractive benefit of high scalability, as you aren’t using any application server resources to store client data. However, there are also a number of disadvantages. One disadvantage for storing state information in cookies is that some browsers limit cookie size—which prevents you from storing large amounts of data in the client scope, and ColdFusion throws an exception if you attempt to store too much data in a client variable.
7.7.
Storing Client State Using a Database
The primary disadvantage related to using cookies to store client data is that users can simply not accept cookies and can edit or delete cookies from their system. For these two reasons, storing client data in cookies should be an option only if your users are in a controlled environment and cannot edit cookie data, or if you are storing simple, nonessential data in the client scope.
7.7. Storing Client State Using a Database You want to store client state information in a database.
Technique Set the attribute clientStorage to the name of a valid ColdFusion data source configured to store client scope data.
Comments This technique creates a ColdFusion application, initializes the client variable scope, and then instructs ColdFusion to use the data source named myDatasource to store client scope information. To store client scope information in a database, you must first ensure the data source is configured to accept client state information. If the database type you are using supports creating tables through SQL scripts, you simply need to create a blank database and point the client storage to that database. ColdFusion builds the table schema required to store client scope data for you. If your database does not support SQL table creation, you need to build the tables yourself. ColdFusion requires two tables to store client scope data in a database: CDATA and CGLOBAL.These tables and their fields are described in Tables 7.2 and 7.3, respectively. Table 7.2 CDATA Table Columns, Data Types, and Descriptions Column Name cfid app Data
Data Type
Description
String of variable length at least 64 characters String of variable length at least 64 characters String of variable length with an indeterminate number of total characters acceptable
Stores the CFID and CFTOKEN for the appropriate user in the format CFID:CFTOKEN. Stores the name of the application used to create the client entry. Stores pound-sign delimited client scope key/value combinations created by the application.
99
100
Chapter 7
Application Flow
Table 7.3 The CGLOBAL Table Column, Data Types, and Descriptions Column Name
Data Type
Description
cfid
String of variable length at least 64 characters
data
String of variable length with an indeterminate number of total characters acceptable
lvisit
DateTime
Stores the CFID and CFTOKEN for the appropriate user in the format CFID:CFTOKEN. Stores pound-sign delimited client scope key/value combinations created by ColdFusion. Stores the DateTime value representing the last time this user visited the application.
Note ColdFusion does not create indexes on the tables it creates to store client scope information. If you want to create indexes to improve performance, you should index the cfid columns of both tables.
Storing client scope information in databases is more often than not the ideal way to manage client data.The disadvantage, obviously, is that you need access to a database system. The advantages though are tremendous—you have complete control over the storage of the data, the system scales much better than when storing in the registry, the system is much more reliable than when storing in client cookies, and security responsibility is delegated to the security options for your database system.
8 Exception Handling
8.0.
Introduction
You just learned about the various ways to control application flow in your ColdFusion application.The CFML programming language allows you to group statements into conditional blocks ( and ) and iterative blocks ().The use of proper flow-control and code-formatting techniques can make your program easy to understand, even for someone unfamiliar with your code. Traditional error handling in C and BASIC subroutines involved a demon that would obscure the logic of the most elegantly written program. Although essential, handling errors should never be the object of your program. After all, your error handling code won’t even be executed if everything goes according to plan, right? Error handling can also clutter an otherwise clean programming API.Traditional functions not only had to return the expected result, they also had to return a myriad of error codes and messages to report if anything went wrong.This often led to confusing semantics, in which the result of the function was not the intended result but was, instead, an error code that your program had to check.The actual result was returned by reference through one of the function’s arguments. For example, the StructAppend() CFML function returns a true/false error code rather than a pointer to the changed structure.The actual result is returned by reference via the struct1 argument. Exception handling was invented to clean up and isolate error handling logic. C++ was one of the first programming languages to support this new concept. ColdFusion has long supported exception handling. ColdFusion MX has refined the exception-handling API a bit to provide additional error information to the programmer.This chapter explores exception handling in ColdFusion MX.You will learn about the / tag syntax to trap and handle different types of errors.You will also look at the / tags for raising new exceptions in your program. Finally, you will build some actual examples that demonstrate proper ColdFusion error handling.
102
Chapter 8
Exception Handling
Before diving headlong into exceptions, pause for a moment to look at the way you would handle errors without exception handling (and the way some programmers might be guilty of using).The following pseudocode illustrates cumbersome error handling. // We will now attempt an operation, such as reading a file // handle the first type of error // handle the second type of error // handle the third error ... // handle the nth error // actual program logic goes here. #result#
This pseudo-routine contains two lines of “getting-stuff-done” code and many, many more lines of error handling.The error handling code is not the problem as much as its placement in the template. It breaks up the flow of the routine and confuses the algorithm. Notice, also, that the return value of the doSomething() function is an error code rather than something more useful. ColdFusion provides a way to separate the error conditions from the main line algorithm through the use of the and tags. creates a block of potentially problematic code, whereas isolates specific error-handling logic.You can use try and catch to simplify the pseudocode: // Attempt an operation, returning a useful result // rather than an error code. // actual program logic goes here> #result# // handle the first error type // handle the second error type ... // handle the nth error type
8.1.
Catching Exceptions
This incarnation of the program is much easier on the eyes.The code that you really care about (that is, the program’s primary logic) appears, uninterrupted, at the top of the block.The error-handling logic takes a back seat to the main algorithm and appears at the end of the block.This is as it should be. Exception handling will enhance your program’s durability as well as its aesthetics. By handling ColdFusion errors in your code, you save your users from being exposed to the all-too-common “An error occurred while processing your request…” standard-issue error templates.
8.1. Catching Exceptions You want to anticipate and handle exceptions within your ColdFusion template.
Technique Use the and tags to anticipate and handle errors in your ColdFusion template. #thefile# The file you requested does not exist.
Comments ColdFusion exception handling is quite simple to understand and use.There are only two little tags you need to worry about, so there is absolutely no excuse for not using them. Use to isolate your mainline logic and to respond to your errors. ColdFusion will abort processing the block the moment an error occurs and will shift control to the appropriate block.This example attempts to read a non-existent file. Reading a file, like any I/O operation, is prone to failure. In this example, you anticipate a possible error by isolating the logic in question with the tag.You use the tag to handle the error within the application and display a friendly error message to the users.
103
104
Chapter 8
Exception Handling
8.2. Catching Multiple Exceptions You want to catch multiple exceptions within your ColdFusion template.
Technique Use multiple instances of within a single block to handle different types of errors. #thefile# The expression is not valid The file you requested does not exist. Some other exception occurred
Comments What happens if more than just one type of error can occur in the midst of a block? ColdFusion allows you to specify multiple blocks, one for each type of error.The type attribute of the tag specifies a specific exception type to be caught.Table 8.1 lists the exception types supported by ColdFusion. Table 8.1 ColdFusion Exception Types Exception Type
application exceptions. exceptions that occur during database operations. ColdFusion page exceptions. exceptions surrounding user security. exceptions thrown when working with objects. exceptions generated by a missing include template. exceptions thrown by invalid CFML expressions. exceptions thrown during synchronized code segments.
8.3.
Examining an Exception
Table 8.1 Continued Exception Type Custom_Type SearchEngine Any
Description Catches exceptions that are defined by you, the developer. Catches exceptions thrown by the Verity search engine. The default. Catches any type of thrown exception.
This example catches, several types of exceptions. I modified the previous example to use a potentially erroneous expression to determine the filename.You must now catch at least two types of exceptions: “expression” (to catch an exception in determining the filename) and “application” (to catch an exception in the file I/O). It also catches expressions of type=”any” to be safe. Astute readers may notice a potential ambiguity in the example’s exception handling code. Expression exceptions can be handled by blocks with type Expression or Any (likewise, I/O exceptions could be considered Application or Any). Both types of blocks appear in the code, so where will expression exceptions be handled? ColdFusion will always use the most precise block available for handling an exception. is used only as a last resort, regardless of the order in which the different blocks appear in the code. Note In addition to the primary 11 exception types, ColdFusion MX introduced over 50 new “advanced” exception types for even more fine-grained control of your application. Consult the MX documentation for a full listing of these new exception types.
8.3. Examining an Exception You want to find out more information about an exception that you have caught.
Technique Use the ColdFusion cfcatch structure to gather more detail about an exception. A #cfcatch.type# exception occurred. #cfcatch.message#: #cfcatch.detail#
105
106
Chapter 8
Exception Handling
Comments Just knowing that an error occurred is often not enough. Usually you want to know what error occurred and why it happened.You can access this information in a block via the implicit cfcatch variable.This variable is populated with useful information at the start of any block.Table 8.2 lists the cfcatch structure’s keys and values. Table 8.2 The Contents of the cfcatch Variable Key
Value
cfcatch.detail
A ColdFusion-supplied detailed message.This message contains HTML formatting and is intended to be displayed in a Web page. Use this variable to help with debugging. A string that represents a specific exception error code.This is used only with exceptions of type=”Custom”. An internal expression error number that is specific to exceptions of type=”Expression”. Custom error information that is not normally displayed. This is used with exceptions of type Custom and Application. The name of the affected lock for exceptions of type=”Lock”.This variable will contain the string “anonymous” if the lock’s name is unspecified. The lock operation that failed, causing a type=”Lock” exception to be thrown.Values may be Timeout, Create Mutex, or unknown. A string representing the exception’s diagnostic message, if available. The name of the missing template in the case of an exception of type=”MissingInclude”. A database-specific error code that is native to the database driver.This variable is provided for exceptions of type=”Database”. SQL state information, if provided by the database driver, associated with exceptions of type=”database”. An array of structures containing the stack trace of all tags that led to the exception, including the tag that threw the exception. The exception type specified in the block.
The example in the previous technique returns you to the familiar I/O example.The code is augmented to output some diagnostic information to help debug the problem. The code includes a debug statement to the block to output the expression’s message, detail, and tagcontext variables. Note that you use the tag to automate the rendering of the contents of the cfcatch.tagcontent variable. This is a good way to become familiar with the values of the cfcatch structure.
8.4. Throwing Exceptions You want to throw custom exceptions in your application.
Technique Use the tag to raise your own exceptions.
Comments ColdFusion gives programmers the capability to create their own types of exceptions that can be thrown and caught just like standard exceptions. Custom exceptions enable your CFML templates to communicate errors that are unique to your application. You can (and should!) use custom exceptions in your application to propagate error conditions.This technique is invaluable when you are writing custom tags or functions. Custom exceptions are the preferred way to notify the calling CFML template that something went horribly wrong. You can roll your own exceptions with the tag.The tag uses the following syntax:
The type attribute can be any of the following: Application, Any, or a custom exception string of your choosing.The message attribute should describe the exception.The detail attribute should provide useful documentation to aid in debugging. ColdFusion will display the value of this attribute if the exception is not caught.The errorCode and extendedInfo attributes are left for you to fill out or leave blank. These optional attributes can be used to provide extra information about a user-defined exception.The object attribute allows you to pass in a subclass of the Java Exception object.You must first define this exception by using the tag.
107
108
Chapter 8
Exception Handling
The previous technique shows an example of throwing a custom exception.The exception is of type MyException and includes a brief message and a more detailed explanation of the error. Note Some compilers, such as the Java compiler, will not compile a source file until all possible exceptions are caught or re-thrown in some fashion. Compile-time error checking like this can help strengthen the quality of your code. The ColdFusion compiler does not warn you about the potential for uncaught exceptions. So be vigilant, ColdFusion developers.
Custom exceptions are handled exactly like their standard counterparts. Custom exceptions are an elegant means for your ColdFusion templates to report errors.You should be liberal with your exception types. Many programmers fall into the trap of throwing and catching exceptions at the broadest level.Try to avoid throwing and catching too many exceptions with type=”Any”. Although doing so may seem expedient at first, you will be robbing your application of some flexibility. An application with many small and focused blocks is more extensible than an application with fewer, but much larger, blocks.
8.5. Re-Throwing Exceptions You want to propagate an exception up to the calling page.
Technique Use the tag to defer the handling of an exception to a template higher up on the call stack.
Comments What happens if you catch something that you did not mean to catch? Ask any old fisherman this question—just throw the darned thing back. ColdFusion provides the tag to do just that.
8.5.
Re-Throwing Exceptions
Sometimes re-throwing an exception is the most appropriate course of action to take. This is usually the case if the template that caught the exception is not completely sure what to do with it. In this circumstance, it is generally preferable to re-throw the exception rather than to make a bad guess. For example, a database query can throw many types of exceptions (distinguished by the SQLState or NativeErrorCode cfcatch variables). All of these exceptions will fall under the broad type, database.Your template is left to decide which types of database exceptions it can handle safely and which are important enough to report to the calling template.The pseudocode fragment shown in the previous technique demonstrates this idea. Note that the tag does not require any attributes.This is because the tag operates in the scope of the block in which it is placed. It merely propagates the current exception, as-is, up the call stack in order for a higher-level template to handle the error.
109
III Using Utility Tags 9
Charting Data
10
Files and Directories
11
Using Internet Protocols
12
Using Verity
13
User Authentication and Authorization
9 Charting Data
9.0.
Introduction
Data can be boring. Although spreadsheets and list views may technically provide all the information necessary to make business decisions, they don’t necessarily make for the most visually appealing applications. Determining the best way to visually display information is one of the primary roles of a ColdFusion developer, and ColdFusion provides the creatively inclined many tools to assist in this ever evolving technical art.The tag is one of these tools. There are numerous reasons to include charts in Web applications. Charts are visually appealing; they add color and spice to your data, and quite simply, they add to the user experience.This chapter discusses the charting capabilities provided by ColdFusion MX and how to best use that functionality to obtain your desired results.
9.1. Creating a Simple Chart You want to create a simple chart.
Technique Use cfchart, cfchartseries, and cfchartdata to create a simple chart.
114
Chapter 9
Charting Data
Comments To create the most basic chart in ColdFusion, you must create a chart object using the tag, you must create a chart series object inside of the chart object using the tag, and then you must define the value points for the series. The code in the previous technique provides values only for the required items needed to create a chart. As you can probably imagine, there are numerous optional attributes you can use to further manipulate the display and behavior of a chart. Execute the code in the previous technique and take a look at the generated chart.The next few sections cover how to manage the appearance and behavior of the chart container, the series in the chart, as well as the individual data points.
9.2. Managing the Chart Container You want to manage the chart container portion of a chart object.
Technique Provide values for the optional attributes to manage the chart container portion of a chart object.
Comments Rarely will you create a chart in ColdFusion and accept the default values for all the optional attributes in the tag as you did in section 9.1.You will most likely control the display of the chart to complement the design of your specific application. There are numerous optional attributes you can supply to the cfchart tag to control the chart container. Basically, the chart container is responsible for everything in the chart except for the actual series and data points.That means you can provide attributes
9.2.
Managing the Chart Container
defining the width and height of the chart container, manage the format and display of the axis values, control display of the legend, and define colors for different sections of the container, among other things. In the previous technique, you defined the height and width of the chart container, defined how many gridlines should appear on the y-axis of the chart, scaled the chart to a specific value on the y-axis, and adjusted the tooltip behavior to appear on mouseDown. These are just a few of the many attributes available for the tag.Table 9.1 lists all available attributes and values and describes their respective behaviors. Table 9.1 Optional Attributes and Behaviors Attribute
Optional Values and Behaviors
backgroundColor
Hexadecimal value or named Web color. Controls the color between the border and the chart data area. Default is white. Desired chart height in pixels. Default is 240. Desired chart width in pixels. Default is 320. Hexadecimal value or named Web color. Controls the color between the border and the chart data area. Default is white. One of four font names: arial, arialUnicodeMS, times, or courier. Default is arial. Defines font bold style. Yes or No. Default is No. Defines font italic style. Yes or No. Default is No. Defines font size as an integer value. Default is 11. Hexadecimal value or named Web color. Controls the color of objects on the foreground such as the gridlines, the axis lines, the axis value markers, and the border. Default is black. Defines the format of the chart output. Accepted values are flash, jpg, and png. Default is flash. Integer number of gridlines to display on the chart value axis. Default is 3. Format to display values on y-axis. Accepted values are currency, date, number, and percent. Default is number. Desired marker size in pixels. Default is determined at runtime. String value for creating a ColdFusion variable from the output of the chart. Primarily used for creating a chart and then writing the chart to a file. Note also providing a value for this attribute causes the chart to not display on the resulting page. For a pie chart, defines whether the pie is sliced or not. Accepted values are sliced and solid. Default is sliced. Creates a horizontal bar chart by rotating the graph axis. Yes or No. Default is No.
chartHeight chartWidth dataBackgroundColor font fontBold fontItalic fontSize foregroundColor
format gridlines labelFormat markerSize name
pieSliceStyle rotated
115
116
Chapter 9
Charting Data
Table 9.1 Continued Attribute scaleFrom scaleTo seriesPlacement
Optional Values and Behaviors Integer value for minimum y-axis point. Default is determined at runtime. Integer value for maximum y-axis point. Default is determined at runtime. For charts with more than one series, defines the position of the series combinations. Accepted values are cluster, default, percent, and stacked. Default is default. Determines whether the chart will display as three-dimensional. Yes or No. Default is No. Determines whether a border will be placed around the entire chart container. Yes or No. Default is No. For a chart with more than one series, determines whether a legend is displayed. Yes or No. Default is Yes if there is more than one series. For series with type of curve, line, and scatter, determines whether markers are shown at value points. Yes or No. Default is Yes. Determines whether grid is shown for x-axis. Yes or No. Default is No. Determines whether grid is shown for y-axis. Yes or No. Default is Yes. Alphabetizes values along the x-axis. Yes or No. Default is No. Hexadecimal value or named Web color. Controls the background color of the value points in the chart. Note this applies only to flash format charts. Default is white. Defines which action causes the tip to show for a value point. Accepted values are mouseDown, mouseOver, and Off. If chart format is flash, mouseDown requires a mouse left-click to show the tip. If not flash, the mouseDown behavior is the same as mouseOver. mouseOver shows the tip on a mouse fly-over. Off turns off the tip functionality. Default is mouseOver. Defines the URL to jump to when a value point is clicked. No default. String value to display as a title for the x-axis. No default. For 3D charts, any number between –1 and 1. Defines the angle to use in the third dimension for the x-axis. Default is .1. String value to display as a title for the y-axis. No default. For 3D charts, any number between –1 and 1. Defines the angle to use in the third dimension for the y-axis. Default is .1.
9.3.
Managing Chart Series
9.3. Managing Chart Series You want to manage the series objects inside a chart object.
Technique Provide values for attributes to manage the series inside a chart object.
Comments Section 9.2 defined how to control the display and behavior of a chart container. A chart container is useless without a series of data to actually populate the chart.You manage the display of the series object using the tag.You use this tag to define the type of series to display the style and color of the markers among other attributes. Table 9.2 lists all available attributes and values and describes their respective behaviors. A number of these optional attributes involve using a query object as data for populating the chart. Using queries to create graphs is discussed further in the next section.
117
118
Chapter 9
Charting Data
Table 9.2 Optional Attributes and Behaviors Attribute
Optional Values and Behaviors
colorList
Hexadecimal value or named Web color. Used only for chart series with type of Pie. Controls the colors displayed for each value in the chart. Default is determined at runtime. Defines which column of a query object represents the item along the xaxis. Determines the display style of value points when chart is of type curve, line, and scatter. Accepted values are circle, diamond, letter, mcross, rectangle, rcross, snow, and triangle. Default is rectangle. Determines the display style of a filled data series. Accepted values are light, plain, raise, and shade. The name of the ColdFusion query object containing the itemColumn and valueColumn to populate the data series. Hexadecimal value or named Web color. Controls the color of the series object. String name of the series; appears in the tip displayed for each value point and in the legend if more than one series is defined. One of the 10 supported ColdFusion chart types: area, bar, cone, curve, cylinder, line, pie, pyramid, scatter, or step. Defines which column of a query object represents the item along the yaxis.
itemColumn markerStyle
paintStyle query seriesColor seriesLabel type valueColumn
Charts with multiple series are also useful tools.You can create multiple series of data within a chart by using more than one tag. It is up to the chart designer, of course, to determine the best way to present the data within the chart—with a number of tools at your fingertips, the helps you create the most appealing, useful chart for your application. The previous technique created a chart with two series.The first series is an area type series with shaded fill color.The second series is a line series with diamond value points. You can add as many series to your chart as you see fit but be careful not to clutter the information so much that it becomes difficult to understand. The only required attribute for is the type attribute.You can define the type of series as one of the following: area, bar, cone, curve, cylinder, line, pie, pyramid, step, and scatter. Figures 9.1 through 9.3 display the many different types of charts, using the code in Listing 9.1. Note that if the cfchart attribute show3d was not set to “yes” that the bar and cylinder chart types would look identical, as would the cone and pyramid types.
9.3.
Managing Chart Series
Listing 9.1 The 10 Supported CFMX Chart Types
8
8
7.111
7.111
6.222
6.222
5.333
5.333
4.444
4.444
3.556
3.556
2.667
2.667
1.778
1.778
0.889
0.889 0
0 0
1
2
8
8
7.111
7.111
6.222
6.222
5.333
5.333
4.444
4.444
3.556
3.556
2.667
2.667
1.778
1.778
0.889
0.889
0
0
1
2
0
1
2
0 0
1
2
Figure 9.1 Chart types: area, bar, cone, and curve.
119
120
Chapter 9
Charting Data
8
8
7.111
7.111
6.222
6.222
5.333
5.333
4.444
4.444
3.556
3.556
2.667
2.667
1.778
1.778
0.889
0.889
0
0 0
1
2
0
1
2
0
1
2
8 7.111 6.222 5.333
0 5(26%)
4.444
1 8(42%)
3.556
2 6(32%)
2.667 1.778 0.889 0
Figure 9.2 Chart types: cylinder, line, pie, and pyramid. 8
8
7.111
7.111
6.222
6.222
5.333
5.333
4.444
4.444
3.556
3.556
2.667
2.667
1.778
1.778
0.889
0.889
0
0 0
1
2
0
Figure 9.3 Chart types: step and scatter.
1
2
9.5.
Populating Charts with Query Values
9.4. Populating a Chart Series with Explicit Values You want to define data points inside a chart.
Technique Use the tag to explicitly define data points within a chart series.
Comments The tag is used to explicitly define data points to populate a chart series. accepts one required and one optional attribute.The required attribute is value and it must be a simple value.The value represents the y-axis.The optional attribute is item. Item represents the label for the x-axis. Note The item attribute of the tag must contain a simple value, because ColdFusion must be able to convert the value to a numeric. Simple values include variables of the following types: boolean, date/time, string, and numbers.
9.5. Populating Charts with Query Values You want to use a query object to define the data points inside a chart.
Technique To populate a chart with query data, use the appropriate cfchartseries optional attributes to define the name of the query used, the column representing the x-axis, and the column representing the y-axis.
Comments Creating graphs from ColdFusion query objects is a powerful feature of cfchart.(For more information on ColdFusion query objects, see Chapter 5, “Queries.”) To take advantage of this feature, you need to provide a valid query object name as the value for the query attribute of the tag.You also need to define which column of the query contains data for the x-axis (or valueColumn) and which column contains data for the y-axis (or itemColumn).
9.6 Implementing Click-Through Behaviors in Charts Youc want to allow the users to click a specific value in the chart and execute a URL.
Technique Use the url attribute of the tag to define the target URL on a click event.
Comments The url attribute of the tag enables you to click through charts and drill down into more specific data or jump to another URL altogether. Note however that the same URL is used for the entire chart. ColdFusion does provide a variable scope for the developer to capture which series, value, and label the user clicked.These variables appear syntactically slightly different than other ColdFusion variable scopes.They are named SeriesLabel, ItemLabel, and Value for the clicked series, item, and value, respectively. Listing 9.2 adds to the technique code to pass through these values. Notice the dollar signs ($) encasing the variable names in the url attribute. Listing 9.2 Chart Drill Down with the url Attribute
9.7
Administering Charts Through the ColdFusion Administrator
Listing 9.2 Continued
9.7 Administering Charts Through the ColdFusion Administrator You want to manage chart behavior through the ColdFusion Administrator.
Technique Open ColdFusion Administrator (/cfide/Administrator.index.cfm), log in, and click Charting from the left navigation bar to administer chart behavior.
Comments The ColdFusion MX administrator panel provides a management area for chart-specific settings.Through the administrator you can manage where charts are stored, how many charts to cache, the maximum number of charting threads to run at a given time, and the location to store cached charts. You can choose to have charts cached in memory or on disk, the default being on disk.To serve cached charts faster you can choose to have them stored in memory. If you store them in memory they will serve up faster, although you are reserving a block of memory in which to store them. If you manage a memory-intensive Cold Fusion application, it is better to store the charts on disk. You can also define how many charts to store in the cache.The default is 50.This means that once the 51st chart is requested, the oldest is removed from the cache and the new request takes its place. By default, ColdFusion will allow four charting threads to run at a given time.You can set this number anywhere between 1 and 5.The higher this number, the more stress placed on your application (although only at times when multiple charts are requested simultaneously). If you choose to store the chart cache on disk, which is the default setting, ColdFusion needs a block of space to store the images or Flash files. By default, the cache directory is [install drive letter]:\CFusionMX\charting\cache. If necessary, you can change this directory to any location. As every application is different, there is no global optimal setting for administering charts. However, if you begin to experience slow response in your charting applications, discuss these issues with your ColdFusion MX System Administrator to determine the best charting settings for your application.
123
10 Files and Directories
10.0.
Introduction
Working with files and directories is a powerful function of ColdFusion MX. Using fileand directory-management tags, you can upload files from a client machine, traverse the file system on the application server, and manipulate files and directories on the application server. In this chapter, you learn how to use the and tags to manipulate your file system.
10.1. Reading Files You want to read a file from the application server’s file system.
Technique Use the tag to read the contents of a text file on the application server’s file system.
Comments ColdFusion provides you the capability to read files from the application server file system through the action=”read” setting on a tag.There are three required attributes and one optional attribute for the read action of a cffile.These attributes are explained in detail in Table 10.1.
Required. Must be set to “read” for a read action. Required. Defines the name of a variable to contain the contents of the file. Required. Defines the path to the file on the application server file system. Optional. Defines the character set of the file contents. Default is UTF-8.
variable file charset
Once you execute the cffile call, the contents of the file are available by referencing the variable name specified by the variable attribute.To display the contents of the file, simply wrap tags and pound signs around the variable name in your template, like so: #filecontents#
ColdFusion also provides the capability to read binary files through the readBinary value of the action attribute.This populates the variable name defined in the variable attribute with the actual binary data stored in the requested file. If you need to read a binary file from the file system and then transfer that data through a form or need to write the contents to another file, you must use the ToBase64() function to convert the returned binary data into its Base64 equivalent.
10.2. Writing Files You want to create a file on the application server’s file system.
Technique Use the tag to write a file to the application server’s file system.
Comments ColdFusion provides you the capability to write files to the application server file system through the action=”write” setting on the tag. When using with the action attribute set to “write”, there are three required and four optional parameters.These parameters are described in detail in Table 10.2.
Required. Must be set to “write” for a write action. Required. Defines the absolute path for the new file, including the new filename.Windows uses backslashes in the absolute path; UNIX systems use forward slashes.r a write action. Required. Contains the content to place inside the new file. Optional. Accepted values are Yes and No. If Yes, a new line is appended to the end of the content contained in the output attribute. If No, no new line is appended. Default is Yes. Optional list of attributes to set on the new file. Optional. Defines the character set used to create the new file. Default is UTF-8. Optional. Defines the permission set to UNIX files.
file
output addNewLine
attributes charset mode
Note that if the file defined in the file attribute of a write action call already exists (and if the permissions are set to allow an overwrite on the file system), the content provided in the output attribute will overwrite the content in the existing file. If you want to append to a file instead of overwriting it, see the technique provided in the following section.
10.3. Appending to Files You want to append content to an existing file on the application server’s file system.
Technique Use the tag to append content to an existing file on the application server’s file system.
Comments ColdFusion provides you the capability to append to existing files on the application server file system through the action=”append” setting on the tag.
127
128
Chapter 10
Files and Directories
When using with the action attribute set to “append”, there are three required and four optional parameters.These parameters are described in detail in Table 10.3. Table 10.3 Append Action cffile Attributes Attribute
Description
action
Required. Must be set to “append” for an append action. Required. Defines the absolute path for the existing file including the new filename.Windows uses backslashes in the absolute path; UNIX systems use forward slashes. Required. Contains the content to append to the existing file. Optional. Accepted values are Yes and No. If Yes, a new line is appended to the end of the content contained in the output attribute. If No, no new line is appended. Default is Yes. Optional list of attributes to set on the new file. Optional. Defines the character set used to create the new file. Default is UTF-8. Optional. Defines the permission set to UNIX files.
file
output addNewLine
attributes charset mode
Note that if the file defined in the file attribute does not already exist, the append action will behave exactly like a write action. It will write a new file to the file system without throwing an exception. If you only want to append content to an existing file, you first need to use the FileExists() function to determine whether the file does indeed exist.The following code provides an example of using FileExists() in conjunction with an append action call: New content added to file #myPath# File #myPath# doesn’t exist!
In the previous code, the FileExists() function determines whether the file defined by the myPath variable already exists. If it does exist, content is appended to the file and a message is displayed confirming the action. If the file doesn’t exist, a message is displayed stating that the file doesn’t yet exist.
10.4.
Uploading Files
10.4. Uploading Files You want to upload files from a client machine to the application server’s file system.
Technique Use the tag to upload files from a client machine to the application server’s file system. File Uploaded! Please browse for the file to upload and click submit
Comments ColdFusion provides you the capability to upload files to the application server file system through the action=”upload” setting on the tag. When using with the action attribute set to “upload”, there are three required and four optional parameters.These parameters are described in detail in Table 10.4.
Required. Must be set to upload for an upload action. Required. Defines the absolute path destination for the uploaded file, excluding the filename.Windows uses backslashes in the absolute path; UNIX systems use forward slashes. Required. Defines the name of the form input that contains the file to be uploaded. Optional. Defines a comma-delimited list of accepted MIME types for upload. Optional list of attributes to set on the new file. Optional. Defines the permission set to UNIX files. Optional. Instructs ColdFusion what to do in case of a naming conflict. Accepted values are Error, MakeUnique, Skip, and Overwrite.
destination
filefield accept attributes mode nameConflict
Note The value of the filefield attribute is simply the name of the field containing the path of the file to be uploaded. Do not wrap the name of this field in pound signs as doing so will dereference the variable. This is a common mistake when uploading files with .
The upload action of can only be used in conjunction with a form containing a file to be uploaded. In the previous technique, the user is first presented with a form prompting for a file to upload. After the user clicks submit, ColdFusion uploads the file using the tag and presents the user with a message stating that the file was uploaded. There are two requirements of the form tag necessary to create a form capable of uploading a file to the server. First, the method argument of the form tag must be set to POST. A form without the method argument defaults to a method of GET—which does not permit sending multipart data as a GET means that form data is posted through the URL. Secondly, the form must have an enctype argument set to “multipart/ form-data”.Without these two arguments set correctly, your form will simply post the client path of the file attempting upload, not the file itself. Note that if you use ColdFusion tags instead of HTML tags, the method defaults to POST instead of GET, although the enctype does not default to multipart/form-data. It is always a good idea to use the “accept” parameter when uploading files. Using this parameter specifies which file types your form will accept. If the user attempts to upload a file which has a MIME type not found in the accept parameter, ColdFusion will throw an InvalidUploadTypeException exception.Without the presence of the accept parameter, malicious users are permitted to upload whatever they choose.
10.4.
Uploading Files
The nameConflict attribute is also useful, especially in high traffic situations. If two users attempt to upload a file with the same name, you can control the behavior of the files with the nameConflict attribute. Accepted values for the nameConflict attribute are Error, MakeUnique, Skip, and Overwrite. Specifying Error instructs ColdFusion not to save the file and to throw a FileOverwriteException exception. Specifying MakeUnique instructs ColdFusion to save the file but to provide it a new name (the new name of the file is stored in the cffile.serverFile variable, discussed later in this section). Specifying Skip instructs ColdFusion not to save the file but to continue processing the rest of the page. Specifying Overwrite instructs ColdFusion to overwrite the existing file with the new one. When you execute the upload action on cffile, ColdFusion creates a special readonly structure named cffile which provides the developer detailed information about the upload attempt.The complete contents of the cffile structure are detailed in Table 10.5. Table 10.5 cffile Keys and Descriptions Key Name
Description
attemptedServerFile
The name of the file ColdFusion attempted to save. The absolute path on the client machine of the file ColdFusion attempted to upload. The name of the file ColdFusion uploaded from the client machine, including the extension. The extension (without the .) of the file ColdFusion attempted to upload. The name of the file ColdFusion uploaded from the client machine, excluding the extension. The MIME subtype of the file ColdFusion saved. The MIME content type of the file ColdFusion saved. Boolean value defining whether a file with the same path and name already exists on the application server file system. The size of the file ColdFusion saved in kilobytes. Boolean defining whether ColdFusion appended the uploaded file to another file on the application server file system. Boolean defining whether ColdFusion overwrote an existing file with the new file. Boolean defining whether ColdFusion renamed the file before saving it on the application server file system. Boolean defining whether ColdFusion saved the file on the application server file system. The size of the file ColdFusion overwrote to save the new file if an overwrite was necessary.
Table 10.5 Continued serverDirectory serverFile clientFileExt clientFileName timeCreated timeLastModified
The absolute path of the directory used to save the file on the application server file system. The name of the file ColdFusion saved on the application server file system, including the extension. The extension (without the .) of the file ColdFusion saved on the application server file system including the extension. The name of the file ColdFusion saved on the application server file system, including the extension. Date stamp defining the time the file was saved on the application server file system. Date stamp defining the time the file was last modified on the application server file system.
As with all structures, a useful way to display the keys and values returned with the cffile collection is with the tag. For more information on how to use with structures, and more on structures in general, see Chapter 4, “Structures.” The structure returned from the upload action on a cffile execution has the base name cffile. So to reference the directory path ColdFusion used to save an uploaded file, you simply use the following code after the cffile execution: The file was saved to: #cffile.serverDirectory#
10.5. Manipulating Files You want to move, rename, copy, or delete a file on the application server’s file system.
Technique Use the tag to move, rename, copy, or delete an existing file on the application server file system.
10.5.
Manipulating Files
File #myPath# moved to #myNewPath# File #myPath# doesn’t exist!
Comments ColdFusion provides you the capability to manage existing files on the application server file system through four action paramenters of the action attribute of the cffile tag: move, rename, copy, and delete. The code in this technique provides an example of moving a file from one location (the source) to a new location (the destination).When using with the action attribute set to move, there are three required and four optional parameters. These parameters are described in detail in Table 10.6. Table 10.6 Move Action cffile Attributes Attribute
Description
action
Required. Must be set to move for a move action. Required. Defines the absolute path destination for the moved file. Windows uses backslashes in the absolute path; UNIX systems use forward slashes. Required. Defines the absolute path of the file you wish to move, including the filename.Windows uses backslashes in the absolute path; UNIX systems use forward slashes. Optional. List of attributes to set on the new file. Optional. Defines the character set used to create the new file. Default is UTF-8. Optional. Defines the permission set to UNIX files.
destination
source
attributes charset mode
ColdFusion also provides you the capability to rename files on the application server file system through the action=”rename” setting on the tag, as shown in the following code: File #myPath# renamed to #myNewPath# File #myPath# doesn’t exist!
133
134
Chapter 10
Files and Directories
The available attributes for renaming a file are identical to those for moving a file, except there is no charset attribute. Also remember that the destination must contain the filename for the renamed file in addition to the absolute path. You can copy files on the application server file system through the action=”copy” setting on the tag, as shown in the following code: File #myPath# copied to #myNewPath# File #myPath# doesn’t exist!
The available attributes for copying a file are identical to those for renaming a file except that the destination attribute can optionally supply a filename. You can delete a file on the application server file system through the action=”delete” setting on the tag, as shown in the following code: File #myPath# deleted File #myPath# doesn’t exist!
The action=”delete” setting on the tag accepts only one attribute in addition to action; file should contain the full absolute path of the file you want to delete.
10.6. Listing Directories You want to discover the contents of a directory on the application server file system.
Technique Use the tag to inspect the contents of a directory on the application server file system.
10.6.
Listing Directories
Comments ColdFusion provides you the capability to inspect the contents of a directory on the application server file system through the action=”list” setting on the tag. When using with the action attribute set to “list”, there are two required and three optional parameters.These parameters are described in detail in Table 10.7. Table 10.7 List Action cfdirectory Attributes Attribute
Description
action
Optional because the default is list, this parameter must be left as the default or explicitly set to list for a list action. Required.The absolute path of the directory whose contents you want to list. Optional. File extension restriction for list of returned items. Required. ColdFusion variable name for returned query object. Optional. Comma-separated list of sorted columns and sort directions (asc or desc) to place on the returned query object. Example: “columnName ASC”
directory filter name sort
Executing the list action with returns a query object containing six columns: attributes, dateLastModified, mode, name, size, and type. Attributes contains the file attributes, dateLastModified contains the date string for the last modification of the item, mode contains the UNIX mode for the item (mode returns empty on Windows systems), name contains the name of the item, size contains the size of the item (directories return 0), and type returns dir for directories or file for files. With the list action, it is simple to create a ColdFusion template that will return to the user a page displaying the contents of a directory. An example of this functionality is shown in the following code. #name# #name#
135
136
Chapter 10
Files and Directories
This example code provides a simple page allowing the user to traverse the application server’s file system starting at the c:\ drive. If the type value for an item is dir, the code builds a link to expand that directory. If the type value is file, it simply displays the name of the file. Save the previous code as directory.cfm on your machine and try it for yourself.
10.7. Manipulating Directories You want to create, rename, or remove a directory on the application server file system.
Technique Use the tag to manipulate a directory on the application server file system.
Comments ColdFusion provides you the capability to manipulate a directory on the application server file system through the create, rename, and delete actions on the tag. The code in the previous technique creates a new directory at the path c:\ newdirectory. Save this code to your machine and execute it. Now rename the directory to newdirectoryTest using the following code:
The preceding code renames the directory c:\newdirectory to c:\newdirectoryTest. Save this code to your machine and execute it. Now delete that directory with the following code:
The preceding code deleted the directory located at c:\newdirecoryTest. Note that only empty directories can be deleted. If a directory contains files or other directories, and you attempt delete the directory using , ColdFusion will throw a NonEmptyDirectoryCannotBeDeletedException exception.
11 Using Internet Protocols
11.0.
Introduction
ColdFusion is an effective mediator for marshalling data in and out of different data repositories. Its communication’s API is as broad as it is practical and easy to use. ColdFusion’s Internet Protocol API rounds out its I/O library. A mere seven tags allow you to leverage the most popular Internet protocols to enhance the capabilities of your ColdFusion application. In this chapter, you learn how to issue HTTP requests, send and receive email, query LDAP directories, and communicate with FTP servers.
11.1. HTTP Requests You want to issue a server-to-server HTTP request.
Technique Use the tag to issue a simple HTTP request and inspect the results.
Comments This technique involves using the tag to connect to a URL. It then prints out the result for the users to see. The tag requires but a single attribute: url (see Table 11.1 for a complete listing of the allowed attributes for ).The tag connects to the URL, retrieves the results from the server, stores them in a ColdFusion structure, and returns the results.
138
Chapter 11
Using Internet Protocols
ColdFusion stores these results in a structure named cfhttp.This structure will contain the output of the HTTP request in its filecontent property. A number of other tidbits of information are available to you as well (see Table 11.2 for a complete listing of the cfhttp structure), such as the MIME type, the status code, and the full response header sent by the Web server. The current example uses the tag to display the contents of the cfhttp structure to the users.This is an effective way to examine the breadth of information and metadata that ColdFusion provides to you about an HTTP request. Table 11.1 Syntax Attribute
Value
Url
Required.The absolute URL of the document to be retrieved.The URL must include the protocol (http or https) and the host name. It may or may not include the port. Default: http. Optional.The port number that should be used when issuing the HTTP request. Any port specified in the URL string (for example, http://hostname:port/) takes priority over this argument. Default: 80. Optional.The method to use when issuing the request. Get can be used to retrieve any type of document. Post should be used when posting form data to a CGI program.The tag must be used with the Post option. Default: get. Optional.The username to be used when requesting a secured document. Optional.The password to be used when requesting a secured document. Optional.The name to be assigned to a query constructed out of the results of a call to . Optional. Used when creating a query out of a text document downloaded using the Get option.This attribute specifies the column names to use for the different fields. Leave this option blank if the first row in the text document defines the column names. Optional. If the columns attribute is unspecified, the first row of data in the text file will be used to determine the column names for the query. Optional.The path to a directory in which to store the result of the HTTP request. A cfhttp.filecontent variable is created if this attribute is not specified. Optional (required if Path and Post options are specified).The filename to use when saving the result of the HTTP request.You must specify this variable when using the Post method option. Optional.The delimiter to use when creating a query out of the result document. Default: comma.
Port
Method
Username Password Name Columns
FirstRowAsHeaders
Path
File
Delimiter
11.1.
HTTP Requests
Table 11.1 Continued Attribute TextQualifier ResolveURL
ProxyServer ProxyPort UserAgent ThrowOnError
Redirect
Timeout
Charset
Table 11.2
Value Optional.The text qualifier (if any) to be used when parsing the result document to create a query. Default: “”. Optional.When this option is set to “Yes”, ColdFusion will resolve all URLs in the result document so that the links remain intact. Specifically, ColdFusion will insert the protocol, host name, and port into all embedded references. Default: No. Optional. Host name or IP address of a proxy server (if any) controlling outbound HTTP requests. Optional.The port to be used when issuing an HTTP request to a proxy server. Default: 80. Optional.The user agent request header to be sent to the Web server. Optional.This specifies whether ColdFusion should throw an error if the document cannot be retrieved. If set to “Yes”, and should be used to handle the error. Default: No. Optional.This specifies whether ColdFusion should follow a redirect request from the Web server. If set to “No”, you can use the cfhttp.responseHeader.LOCATION variable to determine whether a redirect request was issued. Default: Yes. Optional.The amount of time, in seconds, the ColdFusion server should wait for an HTTP request to return. ColdFusion will use the lesser of this attribute and the Administrator timeout. If neither are specified, ColdFusion will wait indefinitely for the request to terminate. Optional. A Java character set for the file or URL in an HTTP request. Default: UTF-8.
cfhttp Response Variable
Key
Value
cfhttp.filecontent
The content of the HTTP response, for text and MME files only. The MIME type of the response (for example, “text/html”). A CFML data structure representing the response headers returned from the Web server. Most often, this variable will be a structure with multiple keys (one key per header variable). The raw response header text. The HTTP error code and message string.
cfhttp.mimeType cfhttp.responseHeader
cfhttp.header cfhttp.statuscode
139
140
Chapter 11
Using Internet Protocols
11.2. Sending Email You want your ColdFusion page to send an email message to one or more people.
Technique Use the tag to send a text email. The attached document contains the source code for this ColdFusion MX template.
Comments In this example, the ColdFusion template checks for a submitted email address and uses the tag to send a one-line email message back to the users. This example requires that a valid SMTP mail server has been configured in the ColdFusion administrator and ColdFusion will throw an exception if no such server is present. However, you can use the optional server attribute to specify a mail server at runtime. The required attributes are to, the recipient’s email address; from, the sender’s email address; and subject, the subject of the message.The tag also accepts many optional (but useful) attributes, including cc and bcc, a list of addresses to carbon copy or blind carbon copy the message; type, which can specify text or HTML content; and MIMEAttach, a server-based path to a file that should be attached to the email.
11.3. Receiving Email You want your ColdFusion page to check for email on a mail server.
Technique Use the tag to connect to a POP server and download email messages.
11.4.
Querying an LDAP Directory
Comments This example gathers the minimum amount of information from the users in order to connect to a POP server and download some messages.The template expects the following three variables: popserver, username, and password.The popserver should be the host name or IP address of an available POP server on which the user has an account.The username and password variables should, naturally, contain the username and password for the user’s account. The ColdFusion template uses the tag to pull 10 messages (specified by the maxrows attribute) off of the POP server.The action attribute accepts three possible values: getHeaderOnly, getAll, and delete.The getHeaderOnly option will force the tag to return only the email headers.This will take less time and is the best option to use when displaying a summary listing of email messages. The getAll option causes the entire email message body and any attachments (in addition to the header) to be returned to the calling template.This option is best used to display a detailed view for a smaller number of messages. The delete action will delete one or more messages from the POP server.When using this action, you must also set the messageNumber attribute.This attribute contains one or more message IDs to be deleted.You should note that to delete a message, you must make two calls to : one call to retrieve the headers and message IDs and a second to actually delete the messages.
11.4. Querying an LDAP Directory You want to query an LDAP directory for use in your page.
Technique Use the tag to query an LDAP directory.
141
142
Chapter 11
Using Internet Protocols
Comments The Lightweight Directory Access Protocol (LDAP) was invented in 1995 at the University of Michigan.The protocol was designed to provide access to online directories over TCP/IP. LDAP was a lightweight replacement for the DAP (Directory Access Protocol), which served information housed in OSI X.500-compliant directory servers. LDAP has since found its way into countless back offices, providing access to directories of users, email services, organizational units, and many other types of information. LDAP directories organize the information they contain in a hierarchy. Each element in the tree is assigned a distinguished name (DN) that uniquely identifies it in the directory.The DN is comprised of the element’s relative distinguished name (RDN) and the RDN of its parents. For example, a computer called “computer1” might be given the RDN, “CN=computer1”.This name would uniquely identify the element in the context of its parent container. If the computer belonged to the sales department of the company “mycompany.com”, its DN might be “CN=computer1, OU=sales, DC=mycompany, DC=com”.The computer would also have the following canonical name: “mycompany.com/sales/computer1”. LDAP queries all have a few things in common. First, they all begin their searches at a base DN.This could be the top of the tree (for example, “DC=mycompany, DC=com”) or any other node in the tree. Second, LDAP queries usually have one or more filters to narrow the search. LDAP filters use a prefix format in their syntax. For example, the filter “(&(l=Raleigh)(st=North Carolina))” would find all directory entries with a location of “Raleigh” and a state of “North Carolina”. Finally, an LDAP query usually specifies a list of attributes to return. Attributes are the different fields that an LDAP entry contains.The values that these attributes contain can be stored on the entry or derived by some other means. Attribute names are specific to the type of LDAP entry to which they belong. The example in this section uses the tag with its action attribute set to “query” to perform a query against a user-specified LDAP database.You must define the following attributes in the tag when executing a query: server (the
11.5.
Adding an LDAP Entry
name or IP address of the LDAP server), username (the username of a user authorized to perform the query), password (the user’s password), start (the starting DN where the query will begin), filter (the filter test to be applied to all nodes in the search scope), attributes (the LDAP attributes to be returned from the query), and name (the name of the ColdFusion query object that will house the results).
11.5. Adding an LDAP Entry You want to add an entry to an LDAP directory.
Technique Use the tag with its action attribute set to “add” to add a new entry to an LDAP server.
143
144
Chapter 11
Using Internet Protocols
Comments This example uses the tag to add a new entry to the LDAP directory by assigning the value “add” to the tag’s action attribute and providing the necessary information to create the new entry.The example catches any exceptions that might be thrown by the LDAP request, such as a connection failure or an authentication failure. To add a new entry, you must also provide the following attributes: attributes (a semicolon-delimited list of attribute name/value pairs), dn (the distinguished name to assign the new entry), server (the name or IP address of the LDAP server), username (the username of a user who is authorized to perform this transaction), and password (the authorized user’s password). Take care that you specify all of the required attributes for the type of entry that you are adding. Consult your LDAP server’s documentation to determine the required attributes.
11.6. Updating an LDAP Entry You want to update an existing entry in an LDAP directory.
Technique Use the tag with its action attribute set to ”modify” to update an existing entry on an LDAP server.
11.7.
Adding and Deleting an LDAP Entry’s Attributes
Comments This example updates an existing attribute on an existing LDAP entry. Specifically, it sets John Smith’s title to “VP of Product Development.”To perform this operation, you must specify the following attributes: action (must be set to “modify”), modifytype (what to do with the specified attributes in the case of a multi-valued attribute: “add”, “delete”, or “replace”), attributes (a semicolon-delimited list of attribute name/value pairs to be updated on the entry), server (the name or IP address of the LDAP server), username (the username of an authorized user), and password (the user’s password).
11.7. Adding and Deleting an LDAP Entry’s Attributes You want to add or delete attributes on an existing LDAP entry.
Technique Use the tag with its action attribute set to “modify” to add or delete an attribute on an LDAP entry.
145
146
Chapter 11
Using Internet Protocols
Comments The technique you use to add or delete an attribute is almost identical to how you update an attribute.The only difference is the value of the modifytype attribute in the tag. Setting the attribute to “add” will add the specified attributes if they do not exist. Conversely, setting the attribute to “delete” will remove the attributes from the entry.
11.8. Renaming an Entry You want to change the distinguished name of an LDAP entry.
Technique Use the tag with its action attribute set to ”modifyDN” to change an LDAP entry’s distinguished name.
Comments To rename an LDAP entry, you set the tag’s action attribute to “modifyDN”.The rest of the attributes are the same as when updating an entry’s attribute; only the attributes attribute specifies the item’s new distinguished name.
11.10.
Sending a File via FTP
11.9. Deleting an LDAP Entry You want to delete an entry from an LDAP directory.
Technique Use the tag with its action attribute set to “delete” to remove an entry from an LDAP directory.
Comments Deleting an LDAP entry is really easy; just set the action attribute to “delete” and specify the DN of the item to delete via the dn attribute. Once again, the usual suspects—server, username, and password—are in attendance.
11.10. Sending a File via FTP You want to upload a file from the ColdFusion server to an FTP server.
Technique Use the tag to move a file up to an FTP server.
Comments ColdFusion MX provides FTP support with its tag.The tag can be used to perform any of the various FTP commands that can be executed from a command prompt, including uploading files, downloading files, creating directories, and listing directories. Like the tag, the tag relies on its action attribute to dictate its behavior. In most cases, creates a connection to the FTP server, performs the requested action, closes the connection, and returns the results of the command to the user using the cfftp.returnValue variable. This behavior can be undesirable if you need to perform multiple commands on the same FTP server. In such cases, ColdFusion allows you to cache FTP connections. By using the “open” action, you can create a persistent connection to an FTP server and save the handle in a ColdFusion variable. Subsequent calls to can re-use this connection via the tag’s connection attribute.When you are finished using the FTP connection, you can close it with a final call to using the “close” action. In this example, you do not need to use connection caching because you just need to perform a single FTP operation—uploading a file to an FTP server.The “putfile” action requires the following attributes to be set: username (the username to use when connecting the FTP server), password (the password to use when connecting), server (the name or IP address of the FTP server), localfile (the full path description of the file to be sent), and remotefile (the name of the file to create on the server).
11.11. Getting a File via FTP You want to download a file from an FTP server.
Technique Use the tag to download a file from an FTP server. user: pass:
161
162
Chapter 13
User Authentication and Authorization
Comments This technique determines whether a username and password was submitted to the page. If the credentials authenticate, the user is logged in; otherwise, the login form is displayed. The field names in the login form have a special meaning to ColdFusion.When a form is submitted with the field names j_username and j_password, ColdFusion automatically populates the variables cflogin.name and cflogin.password with their respective values. Although you can simply use form.j_username and form.j_password to access the value of the username and password, using the cflogin scope enables you to use the same authentication code for URL variables or basic HTTP authentication. If you want to restrict access to every page in your application, the application.cfm file is an ideal place to implement logic, because it is implicitly executed before every page request, including when CFCs are invoked as Web services.
13.4. Obtaining the Logged-in User ID You want to determine the user ID of the currently logged in user.
Technique Use the GetAuthUser function to get the user ID of the currently authenticated user. #GetAuthUser()# is cool!
Comments The function GetAuthUser returns the value passed in to the name attribute of the tag.The function returns an empty string if the client is not authenticated.
13.5. Authorizing a Block of Code You want to ensure that only users in a specific role can execute a block of code.
Technique Use the IsUserInRole function to limit the blocks of code that users are allowed to execute.
13.5.
Authorizing a Block of Code
In role: user Not in role: user In role: admin Not in role: admin
Comments The IsUserInRole function returns true or false depending on whether the currently logged in user is in the role passed into the function. Recall that when you invoke the tag, you pass a comma-delimited list of role names into the roles attribute.The IsUserInRole function determines its result by using the list of roles passed in to the tag. Roles tell the application which actions the user can perform. Roles are also known as groups in some security policies. An example of where you can find roles-based security is in a bank. At a basic level, a bank’s employees can be broken into two groups: tellers and account managers.Tellers can make deposits to and withdrawals from a bank account. Account managers can do anything that a teller can do, but also have added permissions to create and close accounts. Even with this simple example, there are several ways to assign the roles. One possibility is to create two roles: one called tellers and the other called account_managers. Another possibility is to create a role for each privileged action.The roles may be called deposit, withdraw, createAccount, and closeAccount.Then, each user would be assigned multiple roles. The roles you define are key to the flexibility and complexity of your authorization system.When you define roles to job titles and then the job descriptions change, you have to change your code. If you define roles to each action, you can end up with a too many roles, which can be complex to handle. Because of this tradeoff between complexity and flexibility, it’s worth spending the time in your design process to contemplate your particular situation before you define the roles.
163
164
Chapter 13
User Authentication and Authorization
13.6. Authorizing a Function You want to ensure that only users in a specific role can execute a particular function.
Technique Use the roles attribute of the tag to specify which roles can execute the function. #GetAuthUser()# has permission to execute userFunc #GetAuthUser()# has permission to execute adminOnly #userFunc()# #adminOnly()#
Comments Roles security can be implemented with the tag through either ColdFusion components (see Chapter 19, “Components,” for more information on CFCs) or user-defined functions (see Chapter 16, “User-Defined Functions,” for more information on UDFs).The tag has an attribute called roles that allows you to specify a comma-delimited list of roles that have permission to execute the function. will throw an exception if the user does not have permission to execute the function.The error message generated by when a user is not in the list of roles is not typically one you want to show to your users. Consider using , , or to catch the exception. See Chapter 8, “Exception Handling,” for more information on dealing with these errors. Note The documentation for ColdFusion MX specifies that the roles attribute of the can only be used when is used in a ColdFusion component. This is not the case—it can be used in a UDF as proven by the example in this technique. Because the actual intent of Macromedia may be different from how it currently works, take note of this issue in future releases.
13.7.
Authentication Example
13.7. Authentication Example You want to authenticate multiple users against multiple repositories.
Technique Use an abstract component and inheritance to build an authentication architecture that can handle multiple users and repositories. application.cfm:
DatabaseAuthenticator.cfc: SELECT UserID, FirstName, LastName, City, State,
13.7.
Authentication Example
Country, Email, Phone FROM users WHERE UserName = ‘#arguments.username#’ AND PassWord = ‘#arguments.password#’ SELECT r.name FROM roles AS r, user_roles AS ur WHERE ur.UserID = #userInfo.UserID# AND ur.RoleID = r.RoleID
Below you will find operations that you can perform in the intranet.
User Options
Edit User Settings change your password, or contact info
Add a Document add a document to the intranet
View Documents view documents in the intranet
Check Email check your email
Administrator Options
173
174
Chapter 13
User Authentication and Authorization
Edit User Settings change password, or contact info for other users
Add a User add a new user to the intranet
Delete User view documents in the intranet
Log Out
Comments Thus far, you have not seen any authentication code that can work with more than one user.This section shows you how to build an application that not only authenticates more than one user, but can also authenticate from several repositories (database, LDAP, and simple). The application.cfm file is easy to read because all the authentication logic has been moved into loginLogic.cfm and a is used to include it. The loginLogic.cfm page includes loginForm.cfm if a username and password are not sent in the page request, or if authentication fails.The login form will prompt the user for a username and password, and display an error message if applicable (see Figure 13.1). If the username and password are supplied, loginLogic.cfm attempts to authenticate the credentials against each authenticator component.The authType variable in application.cfm defines a list of names for each authenticator used by the application. In loginLogic.cfm, instances of each authenticator are created dynamically by looping through the authType list.
13.7.
Authentication Example
Figure 13.1 The output of loginForm.cfm, where the user logs in to the application.
The main design goal of this example is to be able to easily plug-and-play different authentication methods. CFCs (covered in Chapter 19) are a great way to accomplish this goal.The first CFC in this example is a CFC called User, which is used to hold information about a user when logged in. By using the this keyword, the CFC variables are publicly accessible, and can be accessed with dot notation (cfcInstance.variableName). The next CFC is called Authenticator; it defines a framework for the authentication methods (database, LDAP, and simple) to inherit from. Each authentication method will define a CFC that inherits from the Authenticator CFC, and overrides the pseudo-abstract method “authenticate”.The Authenticator CFC holds an instance of a User CFC, which is accessible through the getUser function. CFCs that inherit from Authenticator populate the User object with information when the authenticate method is called. The simple authenticator CFC simply determines whether the username and password are the same. If they match, the user will be logged in.You may notice that the example doesn’t populate all of the fields in the user object because it doesn’t have all the information.This is one advantage to using a CFC to store the user information over a structure—you can define default values. Next take a take a look at the database authenticator.The example uses a database with the following structure, listed in Tables 13.1-13.3.
UserName PassWord FirstName LastName City State Country Email Phone
Table 13.2 The role Table Column Name
Data Type
RoleID Name
Auto incrementing integer (identity field), primary key Text/varchar
Table 13.3 The user_roles Table Column Name
Data Type
UserID RoleID
Integer Integer
The database design allows you to easily modify both the users and the roles independently.The design also allows users and roles to have a many-to-many relationship, meaning each user can have multiple roles, and each role can be assigned to multiple users. The final authenticator, the LDAP authenticator, is perhaps the most powerful yet, because it allows you to connect to enterprise directory servers such as Microsoft Active Directory. By changing some of the default values, or by calling the setDomain, setServer, and setBaseDN functions, you should be able to connect to any Windows 2000 Active Directory and authenticate users against it.The tag is covered in detail in Chapter 11, “Using Internet Protocols.” The main page of the Acme Intranet example (acmeIntranet.cfm) uses the IsUserInRole function to determine which links to show the user, as shown in Figure 13.2.The administrators have more options than regular users. Each page in your application that is restricted to specific roles should call the IsUserInRole function before displaying the page.
13.7.
Authentication Example
Figure 13.2 The main page, acmeIntranet.cfm, shows the appropriate content based on the user’s access level.
Notice that, at the top of the page, the program determines whether the session variables are defined. As mentioned, doesn’t exactly use session variables to maintain state, and because of this, it is possible for session variables to expire before the variables do.
177
IV Database Integration 14
Structured Query Language (SQL)
15
Stored Procedures
14 Structured Query Language (SQL)
14.0.
Introduction
When ColdFusion 1.0 was released there were no .CFM files, no tag, not even . ColdFusion did however have .DBM files and a tag.The DB stood for database; ColdFusion was born to connect the database and the Web browser. ColdFusion can do much more today than it could in its inception; however, its primary purpose is still to connect databases with the Web. Although databases are often integral parts of ColdFusion applications, database design and query performance are often overlooked in the development process. Improving SQL queries and utilizing the facilities of the database server can solve many performance problems. Structured Query Language (SQL) is the common language that all relational databases speak, with a few different dialects. Most of the time, your SQL statement will run without modification on several database servers. SQL has several underused capabilities that I hope you will unleash after reading this chapter. This chapter uses the same database tables to present all of the examples. Table 14.1 stores all of the employees and information related strictly to each employee. Table 14.1 employees Table Column Name
Data Type
EmployeeID
Auto Incrementing integer (identity field), primary key Text/varchar Number/integer Currency/money
Name Age Salary
182
Chapter 14
Structured Query Language (SQL)
Table 14.1 Continued Column Name Resume DepartmentID
Data Type Text Integer (foreign key)
Table 14.2 stores the departments. Each employee must belong to exactly one department, and each department can have several employees.The relationship between departments and employees is called a one-to-many relationship, sometimes noted as 1-N. Table 14.2 department Table Column Name
Data Type
DepartmentID Name
Auto Incrementing integer (identity field), primary key Text/Varchar
Next, you need to store information about the projects; the structure for the projects table is listed in Table 14.3. Table 14.3 projects Table Column Name
Data Type
ProjectID Name
Auto Incrementing integer (identity field), primary key Text/Varchar
Each employee can work on more than one project and each project can have more than one employee assigned to it.This is known as a many-to-many relationship or a N-N relationship, and is represented in Table 14.4. Table 14.4 The employee_projects Table Is a Many-to-Many Relationship Column Name
Data Type
EmployeeID ProjectID
Integer Integer
The employee_projects table uses two foreign keys to link the employees and projects table together.The two foreign keys together become the primary key for the employee_projects table. It would be a good idea to populate your database in order to run the examples in the following sections. Most databases provide a user interface that allows you to add data to a table.
14.2.
Updating Data
14.1. Inserting Data You want to add a new row to a table.
Technique Use the INSERT INTO and VALUES keywords to insert a new row in to a table. INSERT INTO employees (Name, Age, Salary, DepartmentID) VALUES(‘Bob’, 31, 50000, 1)
Comments Inserting data into a database is fairly easy compared to selecting data, which is why it’s covered first.The INSERT keyword is used to tell the database that you want to add data to it.You use the INTO keyword to tell the database which table you are inserting into. After the table name, a list of columns is specified, and finally a list of values. You may notice that you don’t need to specify every column defined in the table to insert. EmployeeID isn’t included because it is defined in the database as an autonumbering identity, which means the database will populate that field automatically when you perform the insert.The Resume field is not included in this INSERT statement either; you may leave fields out of the INSERT statement if they are defined in the database to allow NULL values, or don’t require a value.You can also set up your database to populate fields with default values. Although it’s not very common anymore, from time to time developers may omit the list of column names from the table in their insert statement.This will not cause an error on most databases, but it will eventually make someone’s life difficult, and possibly your own.When the column list is not present, the database will use the order in which the fields were created to determine where to place which value.This is something to avoid if you’re at all concerned with writing maintainable code. INSERT INTO employees VALUES(‘Bob’, 31, 50000, 1)
14.2. Updating Data You want to update one or more columns in an existing row.
Technique Use the UPDATE and SET keywords to change data in your database.
183
184
Chapter 14
Structured Query Language (SQL)
UPDATE employees SET Salary = 1000000, Name = ‘Rich’ WHERE EmployeeID = 1
Comments To change the data in your tables, the UPDATE keyword is used. After the UPDATE keyword, the table name is specified, and then the SET statement tells the database which values to update. Several fields can be updated at once by separating them with commas in the SET clause. Rows are typically updated one at a time, and a good way to do this is by testing the primary key in the WHERE clause. If you omit the WHERE clause, all the rows in the table will be updated.The WHERE clause is discussed in detail later in this chapter.
14.3. Deleting Data You want to delete a row from a table.
Technique Use the DELETE keyword to delete rows from your table. DELETE FROM employees WHERE EmployeeID = 1
Comments When you delete data from a database with SQL, you should use a WHERE clause to limit which rows will be deleted (just as you do with the UPDATE statement). If you don’t include a WHERE clause, every row in your table will be deleted. Microsoft Access requires that you specify columns to delete from after the DELETE keyword. DELETE * FROM employees WHERE EmployeeID = 1
14.5.
Limiting Rows Returned
14.4. Selecting Data You want to select some data from a database.
Technique Use the SELECT statement to retrieve information from the database. SELECT Name FROM employees
Comments The trick to mastering SQL is mastering the SELECT statement. Retrieving information from the database that you need is typically much more difficult than manipulating or adding data. The query shown here can be used to select the names of all employees from the database.The SELECT keyword tells the database which action you are performing. After the SELECT keyword, you specify a list of columns. In this example, you just want the employee’s name, so you simply write Name.The FROM keyword tells the database from which table(s) to return data. Many novice SQL developers might write the SQL in this technique the following way: SELECT * FROM employees
This code still works, but it returns the EmployeeID, Age, Salary, Resume, and DepartmentID along with the employee names. SELECT * means to return all columns in the table; this often means that you are asking the database to do more than it needs to. Never select more information than you need. Not only can this shortcut get you into trouble with the performance police (they’re out there, watch out!), but it also makes it difficult to maintain the code. The tag is used to display the results of any variable (passed in through the var attribute) neatly in a table. It’s used here, and throughout the chapter, to display the results of the query.
14.5. Limiting Rows Returned You want to return rows that meet a certain condition.
Technique Use the WHERE keyword to limit the rows returned. SELECT Name FROM employees
185
186
Chapter 14
Structured Query Language (SQL)
WHERE Name = ‘Pete’
Comments Because you usually don’t need to return all the rows in a table, SQL offers the WHERE clause.The WHERE clause allows you to limit the results returned.This example returns all employees named Pete. Notice that you must place single quotes around ‘Pete’ to indicate that it is a string.This is required for strings. On numeric fields, the single quotes are not allowed.This requirement is a common source of error. Several operators are available for use within a WHERE clause; some of the common ones are outlined in Table 14.5. Table 14.5 Common SQL Operators Operator
Meaning
=
Equal to Not equal to Greater than Less than Greater than or equal to Less than or equal to In a list of values (see Section 14.6) Matches a pattern (see Section 14.7) Logical AND Logical OR
> < >= 100000 AND Age < 30
14.8.
Using Aliases
Comments The SQL in this technique selects all employees that have salaries larger than $100,000 and are younger than 30 years of age.The AND operator is used to indicate that both conditions must be true.The OR operator is used syntactically exactly the same way as the AND operator but it holds a different meaning. You can use parentheses to group together OR and AND statements, much like you can with .
14.7. Sorting Results You want your result set to be sorted by one or more columns.
Technique Use the ORDER BY keywords to sort the result of a query by a specific column or columns. SELECT Name, Age FROM employees ORDER BY Name DESC, Age
Comments The ORDER BY keywords are followed by a list of columns that have been selected in the SELECT statement.The results are sorted in ascending order by default.You can also change the order by using the DESC (descending order) keyword or the ASC (ascending order) keyword.This SQL statement returns all names and ages first sorted by name (Z-A descending order). If any rows have the same name, they are sorted by age.
14.8. Using Aliases You want to refer to columns or tables as different names.
Technique Use the AS keyword to create an alias. SELECT e.Name AS EmployeeName FROM employees AS e
187
188
Chapter 14
Structured Query Language (SQL)
#alias.EmployeeName#
Comments The AS keyword can be used to create an alias to a column name in the result set, or to create an alias to a table name used within the SQL statement.The syntax for the keyword is the same in both cases; after the real name for the object, you add AS AliasName. Using column name aliases is useful in aggregate functions (covered in Section 14.12).Table name aliases are useful when joining tables, which is covered next.
14.9. Selecting from Multiple Tables You want to pull data from more than one table.
Technique Specify multiple tables in the FROM statement to select data from multiple tables. SELECT e.EmployeeID, e.Name, e.DepartmentID, d.DepartmentID, d.Name FROM employees AS e, departments AS d
Comments A join allows you to retrieve related information from multiple tables in a single query. The output of the code in this technique, which includes two employees and two departments in the database, is shown in Table 14.6. Table 14.6 Result of This Technique EmployeeID
Name
DepartmentID
DepartmentID
Name
1 1 2 2
Emp1
1 1 2 2
1 2 1 2
Dept1
Emp1 Emp2 Emp2
Dept2 Dept1 Dept2
The database returns the cross product (or Cartesian product) of employees and departments.This is known as a cross join, and is essential to understanding inner and outer
14.11.
Joining Three Tables
joins.The total number of records returned (the recordcount) in a cross join is always the number of rows in the first table multiplied by the number of rows in the second. This means that if either your employees table or your departments table have zero records, the query would not return any rows, because zero multiplied by anything is zero.That rule is important to keep in mind when you are performing inner joins, and motivates the need for outer joins.
14.10. Joining Two Tables You want to select related data from two tables.
Technique Use a WHERE statement that requires that the primary key in one table match a foreign key in the other table. SELECT e.Name AS EmpName, d.Name AS DeptName FROM employees AS e, departments AS d WHERE e.DepartmentID = d.DepartmentID
Comments The SQL in this technique is very similar to the previous technique except that it adds a WHERE statement.The WHERE statement limits the result of the cross product to the rows in which the DepartmentIDs from the employees and departments tables match.You can see in Table 14.6 that the DepartmentIDs from the employees table and department table match in the first and last row. Only the two matching rows are returned in this query, instead of a complete cross product. In this query, the employee’s DepartmentID is the foreign key and the department’s DepartmentID is the primary key.The resulting query shows each employee along with the department they belong to.
14.11. Joining Three Tables You want to select related data from three tables.
Technique Use a WHERE statement with two conditions that match the primary keys with the foreign keys.
189
190
Chapter 14
Structured Query Language (SQL)
SELECT e.Name AS EmpName, p.Name AS ProjName FROM employees AS e, projects AS p, employee_projects AS ep WHERE e.EmployeeID = ep.EmployeeID AND ep.ProjectID = p.ProjectID ORDER BY e.Name
Comments The result of this technique is a complete list of all employees assigned to projects. Notice that it includes two join conditions because you are selecting from three tables. Here the employee_projects table holds foreign keys to the employees and projects tables.
14.12. Grouping Data with CFOUTPUT You want to display data in groups.
Technique Use the group attribute of the tag to output data in groups. SELECT e.Name AS EmpName, p.Name AS ProjName FROM employees AS e, projects AS p, employee_projects AS ep WHERE e.EmployeeID = ep.EmployeeID AND ep.ProjectID = p.ProjectID ORDER BY e.Name #empProjects.EmpName#
#empProjects.ProjName#
14.13.
Performing Outer Joins
Comments The tag provides a useful attribute, called group, that allows you to take a query like the one described in the previous section and group the data by a column in that query. For instance, you can group by the EmpName column to display each employee and the projects they are assigned to.The nested tag is used to iterate over each project, and the outer tag is used to iterate over each employee.
14.13. Performing Outer Joins You want to perform a join that returns all rows even if the keys do not match.
Technique Use the LEFT OUTER JOIN keyword to join all rows in a table. SELECT e.Name AS EmpName, ProjectID FROM employees AS e LEFT OUTER JOIN employee_projects AS ep ON e.EmployeeID = ep.EmployeeID
Comments The joins you have seen thus far are known as inner joins, or cross joins. In many database implementations, there exists another type of join, known as an outer join.There are three types of outer joins: left outer join, right outer join, and full outer join. This query returns all employees in the table and their project IDs, whereby an inner join would have returned only the employees that had project IDs (employees who were assigned to a project).The query returns NULL in the ProjectID field for those employees who don’t have a Project ID. If you were to change the LEFT OUTER JOIN in the query to a RIGHT OUTER JOIN, the query would return all the projects, even the ones that didn’t have any employees assigned to them.This is known as a right outer join.The EmpName field would be NULL for those projects that do not have an employee. A FULL OUTER JOIN would return employees who aren’t assigned to any projects, as well as projects that aren’t assigned to any employees. Here, either the ProjectID field or the EmpName field can be NULL, but never both in the same row.The code in this technique can be changed to a full join by replacing LEFT OUTER JOIN with FULL OUTER JOIN.
191
192
Chapter 14
Structured Query Language (SQL)
14.14. Selecting Unique Values You want to select only distinct values for a particular column.
Technique Use the DISTINCT keyword to select only unique values from a table. SELECT DISTINCT Salary FROM employees
Comments The DISTINCT operator ensures that there are no duplicate values for a specific column in a result set.This query displays a list of all the different salaries that employees currently have.
14.15. Using Aggregate Functions You want to perform an operation (such as an average or sum) against multiple rows in the database.
Technique Use an aggregate function such as AVG() to perform the operation on all the rows in the table. SELECT AVG(Salary) AS AvgSalary FROM employees The average salary is #DollarFormat(avgSalary.AvgSalary)#
Comments Aggregate functions allow you to perform operations (such as averages) on all of the values in a particular column.This query shows you the average salary in the organization.
14.16.
Grouping Aggregate Data
The result of this query is one row with one column (called AvgSalary). A query that contains aggregate functions can contain multiple aggregate functions, but cannot select non-aggregate data (for example, average salary and maximum salary may be selected together, but you cannot add Name to the SELECT statement). In order to use nonaggregate functions, you have to use a GROUP BY clause, covered in the next section. Table 14.7 lists some common aggregate functions. Table 14.7 Common SQL Aggregate Functions Function
Meaning
AVG(column)
Average of all values in column Maximum value in column Minimum value in column The sum of all values in column The number of values in the column
MAX(column) MIN(column) SUM(column) COUNT(column)
These aggregate functions can only be used with numeric columns, except for the COUNT() function, which can be used on any type of column.
14.16. Grouping Aggregate Data You want to group together related data.
Technique Use a GROUP BY clause to specify which columns to group by. SELECT d.Name, AVG(Salary) AS AvgSalary, AVG(Age) AS AvgAge FROM employees AS e, departments AS d WHERE e.DepartmentID = d.DepartmentID GROUP BY d.Name
Comments With a GROUP BY clause, you can force aggregate functions to work only on groups of data.This query shows the average salary and average age in each department.
193
194
Chapter 14
Structured Query Language (SQL)
14.17. Limiting Aggregate Results You want to place a condition on aggregate functions.
Technique Use a HAVING clause to limit the results of an aggregate function. SELECT d.Name AS department FROM employees AS e, departments AS d WHERE e.DepartmentID = d.DepartmentID GROUP BY d.Name HAVING AVG(e.Age) > 30
Comments The HAVING clause is used to place a condition on aggregate functions.You can use the query shown here to determine which departments have an average age above 30. The GROUP BY clause is required when you use a HAVING clause with non-aggregate function arguments in the SELECT clause.
14.18. Using the IN Keyword You want to select records with field values found in a predetermined list of values.
Technique Use the IN keyword to select within a list of values. SELECT Name FROM employees WHERE Age IN (30, 40, 50)
14.19.
Using IN with Web Forms
Comments The IN keyword is a useful shortcut when you have a list of possible values for a column. This query returns the names of employees with ages 30, 40, or 50. IN does not introduce any new functionality.The same query can also be written with the OR and = operator (as shown next). SELECT Name FROM employees WHERE Age = 30 OR Age = 40 OR Age = 50
However, it is much easier to use IN, especially when you have a list of values.
14.19. Using IN with Web Forms You want to select data based on which check boxes are enabled.
Technique Use the list generated from a check box in the IN statement. SELECT DISTINCT DepartmentID, Name FROM departments #depts.Name# SELECT e.Name AS EmpName, e.Age, e.Salary, d.Name AS DeptName FROM employees AS e, departments AS d WHERE e.DepartmentID IN (#form.DepartmentList#) AND e.DepartmentID = d.DepartmentID ORDER BY DeptName
195
196
Chapter 14
Structured Query Language (SQL)
Employees in #DeptName#
Name
Age
Salary
#EmpName#
#Age#
#Salary#
Sorry No Employees.
Comments The IN keyword comes in handy when you are working with HTML forms, specifically with check boxes and multiple select lists.The users selection gets translated into a comma-separated list in ColdFusion; exactly what the IN keyword takes as an argument. This example page allows users to check multiple departments and view all employees in each department. IN statements can also be used with text values; however, each value needs to have single quotes wrapping them.You can use ColdFusion’s ListQualify function to add single quotes to the list. Lists are discussed in depth in Chapter 2, “Working with Lists,” and ListQualify is discussed in Section 2.8, “Adding Qualifiers to a List.”
14.20. Matching a Wildcard Pattern You want to match any number of characters to a field.
Technique Use the LIKE operator with the % character to match a wildcard pattern. SELECT Name FROM employees
14.21.
Matching a Single Character
WHERE Name LIKE ‘%Jr.’
Comments The LIKE operator in SQL allows you to match wildcard patterns against text fields in your database.The first wildcard is the % character, used to denote a string of zero or more characters.Table 14.8 explains the meaning of other wildcards available in SQL. The code in this listing will return any name that ends in Jr., which should find everyone in the database that is a junior. Table 14.8 Wildcards for the LIKE Operator Wildcard
Meaning
%
Match a string of zero or more characters Match any single character Match x, y, or z once Match any character between and including a through z Match any character but x, y, or z Match any character not between a and z Microsoft Access equivalent to % Microsoft Access equivalent to _
_ [xyz] [a-z] [^xyz] [^a-z] * ?
Take note that Microsoft Access uses * and ? for % and _ respectively; however, the syntax for [] is the same.
14.21. Matching a Single Character You want to match any single character in a field.
Technique Use the _ character with the LIKE operator to match a single character. SELECT Name FROM employees WHERE Name LIKE ‘_ob’
197
198
Chapter 14
Structured Query Language (SQL)
Comments Because the _ character will match just one character, this query will match Bob or Rob. The query will not match Robert, because the pattern only accepts three character names.The pattern ‘_ob%’ would match Robert.
14.22. Matching a Group of Characters You want to match a set of possible characters in a field.
Technique Use the [] characters with the LIKE operator to match a range of characters. SELECT Name FROM employees WHERE Name LIKE ‘[Aa]%’
Comments The [] bracket characters are used to hold several characters that can occur in the position that the brackets appear in the pattern.This query matches names that begin with A or a.
14.23. Matching a Range of Characters You want to match within a range of characters in a field.
Technique Use the [] characters with a - (dash) in the LIKE operator to match a range of characters. SELECT Name FROM employees WHERE Name LIKE ‘[A-Ka-k]%’
14.25.
Excluding a Range of Characters
Comments This query matches any name that begins with any letter, within the range A through K (in upper- or lowercase).This effectively matches the first half of the alphabet.The dash - character is used to represent the range.
14.24. Excluding a Group of Characters You want to match any characters, except those specified, to a field.
Technique Include the ^ character at the beginning of the bracketed text to exclude characters from the pattern. SELECT Name FROM employees WHERE Name LIKE ‘[^Bb]ob%’
Comments This query will match Rob, but will not match Bob or bob.This query will match any name that doesn’t start with B or b followed by ob.
14.25. Excluding a Range of Characters You want to match any characters, except those within a specified range, to a field.
Technique Include the ^ character within the brackets before a range to exclude the range from the pattern. SELECT Name FROM employees WHERE Name LIKE ‘[^0-9]%’
199
200
Chapter 14
Structured Query Language (SQL)
Comments This query returns all names that do not start with a number.The ^ character is used to exclude the range from the pattern.
14.26. Using Prepared Statements You want to improve database performance on frequently executed queries without storing code on the database.
Technique Use the tag to specify a bind parameter. SELECT Name, Age, Salary FROM employees WHERE EmployeeID =
Comments When a SQL statement is to be processed by the database engine, it must first parse the SQL statement to create an execution plan.The execution plan is created based on how the table is stored internally, which fields are indexed, and so on. Because this operation takes valuable milliseconds, several databases store a cache of execution plans. Most queries executed in ColdFusion applications have dynamic variables in them. SELECT Name, Age, Salary FROM employees WHERE EmployeeID = #EmployeeID#
The variable EmployeeID can potentially represent thousands of values. Each time this query is executed with a different EmployeeID, your database server sees it as a different query. Although technically each query is in fact different, you can see that the query is the same except for the variables. Fortunately, there is a way to relay this information to the database so it can cache just one query, instead of thousands of slightly different queries. Typically, the databases that maintain a cache of execution plans also allow you to tell the database where dynamic variables are in the SQL so that it can cache just one execution plan.This is where the performance benefits come in to play. Smaller caches mean efficient retrieval, and because the cache size is finite, they allow all possible queries to be cached. SQL statements that notify the database where variables exist in
14.26.
Using Prepared Statements
the query are known as prepared statements.The actual syntax to bind parameters to the SQL can vary between vendors, but ColdFusion allows you to write vendor-neutral queries with the tag. At a minimum, you should pass the tag a CFSQLTYPE, which is used for data type validation, and a value.There are several data types that you can use, outlined in Table 14.9. Table 14.9 CFSQLTYPES for CFQUERYPARAM CFSQLTYPE CF_SQL_BIGINT CF_SQL_BIT CF_SQL_BLOB CF_SQL_CHAR CF_SQL_CLOB CF_SQL_DATE CF_SQL_DECIMAL CF_SQL_DOUBLE CF_SQL_FLOAT CF_SQL_IDSTAMP CF_SQL_INTEGER CF_SQL_LONGVARCHAR CF_SQL_MONEY CF_SQL_MONEY4 CF_SQL_NUMERIC CF_SQL_REAL CF_SQL_REFCURSOR CF_SQL_SMALLINT CF_SQL_TIME CF_SQL_TIMESTAMP CF_SQL_TINYINT CF_SQL_VARCHAR
Besides adding a performance boost, using also improves security with its data type validation.The security vulnerability that it protects against is a serious one, and is covered in detail in Appendix B, “Security.” Even if your database doesn’t support prepared statements, it’s still a good idea to use in all queries for its security protection. Using has many of the same benefits as using stored procedures; however, they allow your SQL code to be stored within the application code (CFML). Bind parameters are a simple way you can increase your query performance and security
201
202
Chapter 14
Structured Query Language (SQL)
without implementing stored procedures. Stored procedures do however offer much better security and performance benefits; they are discussed in Chapter 15, “Stored Procedures.”
15 Stored Procedures
15.0.
Introduction
Beginning and intermediate developers often avoid writing stored procedures. Although they can be very complex, in most cases they don’t take much more work than a SQL query.The potential benefits of using stored procedures outweigh the extra work it takes to implement them. Stored procedures allow you to encapsulate database queries and other logic into one procedure.The procedure may take input parameters, and may return a result, similar to ColdFusion user-defined functions. Procedures are stored on the database server (instead of on your application server CFM files), hence the name stored procedures. Stored procedures can be written in several languages. Microsoft SQL Server supports stored procedures written in C++ and C#; Oracle and DB2 support stored procedures written in Java. Stored procedures are typically written in a language that is specific to the database server.Transact-SQL (or TSQL) is commonly used with Microsoft SQL Server, whereas PL/SQL is frequently used with Oracle. All that flexibility is great, but you’re probably thinking: “What’s in it for me?” It turns out that stored procedures have several benefits, including enhanced performance, better security, and code reuse. Stored procedures increase query performance in two ways—first by caching query execution plans for the procedure and second by reducing communication between the database and your application. Stored procedures can also improve your overall application performance by including business logic that might have ended up in your ColdFusion code. The code to call a procedure is usually much smaller than the SQL it will execute; this reduces the traffic sent to the database server. Because stored procedures can manipulate multiple queries, and only return the data you need, they can eliminate multiple
204
Chapter 15
Stored Procedures
trips to the server. Streamlined communication between the database server and application server improves performance, especially in the presence of simultaneous requests. Stored procedures make it easy to enforce a tight security policy on the database server. Database users can be restricted to execute only a few stored procedures rather than execute SELECT, INSERT, UPDATE, or DELETE commands.The use of stored procedures also eradicates the possibility of URL injection hacking (covered in Appendix B, “Security.”). If you’re using stored procedures, you will never have to write the same SQL query twice.The same stored procedure can be used across all applications accessing the database, making code reuse a benefit that makes your job easier. Because procedures are stored on the database server, changes to table or column names can easily be propagated to the procedures on the server. If your application makes use of stored procedures, you can even change database engines without changing a single line of ColdFusion code. Hopefully, by now you can see why you should start using stored procedures if your database supports them. Because stored procedures can do just about anything, this chapter keeps it simple. You will learn enough to convert current queries to stored procedures.To do more complicated tasks, you need to get a book written specifically for your database engine. The examples in this chapter use the database tables presented in the introduction of Chapter 14, “Structured Query Language (SQL).”
15.1. Writing a Simple Stored Procedure in Microsoft SQL Server You want to create a stored procedure in Microsoft SQL Server.
Technique Use a CREATE PROCEDURE statement to define a stored procedure. CREATE PROCEDURE giveRaise AS UPDATE employees SET Salary = Salary * 1.05
Comments The CREATE PROCEDURE statement tells the database that you are defining a new procedure, similar to how the tag tells ColdFusion that you are defining a new function. The name of the procedure is specified after CREATE PROCEDURE. Because the SQL will not be stored in your CFML file, stored procedure names should be descriptive enough so that you can easily tell what the procedure is doing without looking at the
15.2.
Writing a Simple Stored Procedure in Oracle
procedure code.This will improve the readability of your ColdFusion code. Chapter 14 talked about the AS keyword, and how it could be used to make aliases to table and column names. Here, AS is used a little differently; it’s used to mark the beginning of the procedure body. Inside the procedure body, you can simply write SQL statements.The SQL statement in the giveRaise stored procedure gives a five percent raise to all employees. This stored procedure only took one more line of code than its SQL counterpart.The rest of the procedures in this chapter won’t be as easy as this one; however, they also won’t be much more difficult. So forget all your unfounded fears of stored procedures and let’s roll!
15.2. Writing a Simple Stored Procedure in Oracle You want to create a stored procedure in Oracle.
Technique Use the CREATE OR REPLACE along with AS, BEGIN, and END to define a stored procedure in Oracle. CREATE OR REPLACE AS BEGIN
PROCEDURE giveRaise
UPDATE employees SET Salary = Salary * 1.05; END;
Comments The syntax for creating the giveRaise stored procedure in Oracle differs slightly from the Microsoft SQL Server equivalent.The first difference is the OR REPLACE part of the CREATE PROCEDURE statement. OR REPLACE tells the database to replace the procedure definition for giveRaise if one already exists in the database. OR REPLACE is optional; however, it is handy for testing and making changes to stored procedures. Stored procedure definitions in Oracle use the BEGIN and END keywords to define the beginning and the end of the procedure body. Oracle also uses the AS keyword just like Microsoft SQL Server. Although the code for the giveRaise procedure is fairly similar on Oracle and Microsoft SQL Server, as your procedures begin to do more, they will differ quite a bit between database engines.
205
206
Chapter 15
Stored Procedures
15.3. Invoking a Simple Stored Procedure You want to call an existing stored procedure in a database.
Technique Use the tag to invoke a stored procedure and use the tag to assign the result of the procedure to a query object. Employees:
Here is the getEmployeeNames procedure: CREATE PROCEDURE getEmployeeNames AS SELECT Name FROM employees
Comments In this technique, you define a new stored procedure with Microsoft SQL Server syntax that returns a result set.The procedure returns the same result as the first SQL query in section 1 of Chapter 14—the names of all the employees. This example executes the getEmployeeNames procedure with the tag. It uses in its simplest form, by simply specifying the datasource and procedure name.The tag has many of the same attributes as the tag; a complete listing of attributes can be found in Table 15.1. Another way of executing stored procedures is by using T-SQL’s EXECUTE command. The getEmployeeNames procedure can be called from EXECUTE with this SQL statement: EXECUTE getEmployeeNames.
15.4.
Writing a Stored Procedure with Parameters in Microsoft SQL Server
Table 15.1 Attributes Attribute
Notes
procedure
The name of the procedure to execute. The datasource that contains the procedure. The database username. The database password. The maximum number of rows to return from the server in one block. Default is 1. Can be used to improve performance. If true, displays debugging information for the procedure. If true, sets the value of the cfstoredproc.statuscode variable to the procedure’s native return code.
The tag allows you to assign a variable name to the query object returned from the stored procedure.There is nothing special about the query object returned from the procedure, treat it no differently than you would treat a query object returned from the tag. All of the attributes for can be found in Table 15.2. Table 15.2 attributes Attribute
Notes
name
The name of a variable to assign the result set query to. Used to identify a result set when more than one result sets are returned from a procedure.The default value is 1. The maximum number of rows to return from the procedure.The default value is –1, which allows an unlimited number of rows to be returned.
resultset maxrows
When you access a stored procedure from ColdFusion, the database user ColdFusion is using must have EXECUTE or EXEC permission for that stored procedure.
15.4. Writing a Stored Procedure with Parameters in Microsoft SQL Server You want to pass input values to your procedure in SQL Server.
Technique Use a list of @variableName datatype values to define the input parameters of your procedure. CREATE PROCEDURE addEmployee @name varchar(50),
207
208
Chapter 15
Stored Procedures
@age int, @salary money, @deptID int AS INSERT INTO employees (Name, Age, Salary, DepartmentID) VALUES(@name, @age, @salary, @deptID)
Comments Input parameters are defined similarly to how you might define arguments for a function.The variable name is prefixed with an @ symbol, and followed by a data type. Unlike ColdFusion functions, stored procedures require that you specify a data type for the input parameters. CFML is a loosely typed language, but several languages, such as Java and C#, are not.You need to be concerned about types in databases because other languages besides CFML can potentially access the same procedure. The SQL statement refers to the variable with the @ prefix, similar to how you wrap variables with # symbols inside the tag. Notice that you don’t need to wrap single quotes around the @name variable because the stored procedure knows its data type.
15.5. Writing a Stored Procedure with Parameters in Oracle You want pass input values to your procedure in Oracle.
Technique Enclose the parameters in parentheses after the procedure name to define input parameters in Oracle. CREATE OR REPLACE PROCEDURE addEmployee (name IN varchar2, age IN number, salary IN number, deptID IN number) AS BEGIN INSERT INTO employees (Name, Age, Salary, DepartmentID) VALUES(name,age,salary, deptID); END;
15.6.
Invoking a Stored Procedure with Parameters
Comments The parameters in an Oracle stored procedure are enclosed in parentheses. Unlike Microsoft SQL Server, @ signs are not used to prefix variable names. The IN keyword occurs after the variable name. Chapter 14 discussed how the IN keyword can be used to specify a list of possible values for a particular column. Here, you use IN to define the parameter as an input parameter. Note that the IN keyword, depending on its context, can be used for two completely different purposes in PL/SQL. The data type of the parameter is placed after the IN keyword. Variables in PL/SQL don’t use an identifier like the @ symbol in T-SQL, so when you use parameters in this SQL, it can be confusing as to which words are variables and which words are part of the SQL. In this technique, Name is used twice in the SQL statement (they use different case, but PL/SQL is not case sensitive). Fortunately, Oracle is smart enough to know that the first instance of Name is referring to a column name, and the second to a variable name.
15.6. Invoking a Stored Procedure with Parameters You want to pass variables into your stored procedure.
Technique Use the tag to pass variables into the stored procedure. Employee Added.
209
210
Chapter 15
Stored Procedures
Add New Employee Name: Age: Salary: Department: #depts.Name#
Here is the getDepartments procedure: CREATE PROCEDURE getDepartments AS SELECT DepartmentID, Name FROM departments
Comments This example calls the addEmployee procedure defined in sections 15.4 and 15.5, which has four input parameters. Parameters are passed to stored procedures by placing tags inside the tag.The tags should be placed in the same order as the parameters are defined in the stored procedure. The Name, Age, Salary, and DepartmentID form variables are passed into the value attribute of the tag.The cfsqltype attribute allows ColdFusion to validate the data type passed in to the value attribute. A listing of all cfsqltype data types is available in Table 14.9.The type attribute for tells ColdFusion that the parameter in this case is an input parameter.You’ll learn about output parameters in the next section.Table 15.3 lists all attributes for the tag. Table 15.3 Attributes Attribute
Notes
cfsqltype
The data type of the parameter. See Table 14.9 for a list of possible values.
type
IN, OUT, or INOUT, depending on whether the parameter is passing in a vari-
value
able, setting a variable, or doing both. The value of an IN or INOUT parameter. The variable name for the result of an OUT or INOUT parameter.
variable
15.7.
Using Output Parameters
Table 15.3 Continued Attribute maxlength scale null
Notes The maximum length of a parameter. The number of decimal places to scale the parameter to. Used to pass a NULL value in an input parameter.The value attribute will be ignored if this attribute is set to true.
To return all the DepartmentIDs and department names from the departments table, the example uses another stored procedure called getDepartments.The getDepartments procedure is used in the add employee form to construct a list of all possible departments.
15.7. Using Output Parameters You want your stored procedure to return a variable.
Technique Use the OUTPUT keyword to declare a parameter as an output parameter, and then retrieve the value of the variable with by setting the type attribute to “out”. CREATE PROCEDURE addEmployee @name varchar(50), @age int, @salary money, @deptID int, @EmployeeID int OUTPUT AS INSERT INTO employees (Name, Age, Salary, DepartmentID) VALUES(@name, @age, @salary, @deptID) SELECT @EmployeeID = @@IDENTITY
211
212
Chapter 15
Stored Procedures
Your Employee ID is #EmpID#. Add New Employee Name: Age: Salary: Department: #depts.Name#
Comments By adding the OUTPUT keyword to the end of a parameter declaration in the stored procedure in T-SQL, the parameter’s value can be read by ColdFusion after the query has executed.The new addEmployee procedure returns the employee ID of the employee who was added by the procedure.This is done by setting the output variable @EmployeeID to the built-in variable @@IDENTITY, after the INSERT statement.The @@IDENTITY variable holds the value of the employee ID generated automatically by the INSERT statement. The tag tells ColdFusion that you want to read the value of this parameter after the procedure executes by setting the type attribute to “out”.The variable attribute of allows you to assign a ColdFusion variable name to the parameter so you can use it later in your code. In Oracle PL/SQL, the OUT keyword is used instead of OUTPUT.The keyword is placed before the data type in the parameter definition.
15.8.
Working with Multiple Result Sets
15.8. Working with Multiple Result Sets You want to use a stored procedure that returns more than one result set.
Technique Use multiple tags to assign names to each result set. CREATE PROCEDURE getDepartmentsAndProjects AS SELECT Name FROM departments SELECT Name FROM projects
Comments Stored procedures may return more than one result set upon execution, involving fewer trips to the database server. Such a model can be more efficient than using multiple procedures to return multiple result sets. Such a procedure is defined in this section.The getDepartmentsAndProjects stored procedure is defined using SQL Server syntax to return two result sets.The first result set lists the department names and the second is a list of project names.The result sets are returned in the order that they are defined. You can apply a variable name to each result set using tags.The resultset attribute of the tag tells ColdFusion which set to assign the variable name to. Note Because the default value of the resultset attribute is 1, the attribute is not required on the first tag. It is however a good idea to use the resultset attribute for readability when using multiple result sets.
213
V Language Extensibility Features 16
User-Defined Functions
17
ColdFusion Custom Tags
18
CFX API Custom Tags
19
Components
20
Objects
21
WDDX
22
XML
23
Web Services
24
J2EE Interoperability
16 User-Defined Functions
16.0.
Introduction
User-defined functions (UDFs) were one of the most anticipated features of ColdFusion 5. It didn’t take long, however, for ColdFusion developers to discover the limitations of user-defined functions in ColdFusion 5. User-defined functions in ColdFusion 5 had to be defined within tags.This meant that your user-defined functions couldn’t use any ColdFusion tags, only functions. In ColdFusion 5, your creativity was limited to the extent of the built-in function library. With the introduction of the tag in ColdFusion MX, developers can leverage all the features of ColdFusion within UDFs.The tag allows you to use tags within your user-defined function. It also allows you to enforce data-type validation, and the existence of input arguments, as well as enforcing the data type of return values. Because of the improvements of , you will use its syntax exclusively in this chapter.The syntax for creating user-defined functions is covered in Appendix D, “Converting Between Tags and Scripting.” Although user-defined functions are powerful, there are certain tasks that are best left to the other language constructs, such as ColdFusion custom tags (covered in Chapter 17, “ColdFusion Custom Tags”) and ColdFusion components (covered in Chapter 19 “Components”). User-defined functions work well for manipulating a variable and returning some translation of that variable. For instance, you might create a UDF called removeSpaces that removes all spaces from a string. User-defined functions don’t work as well for generating HTML content. For instance, rather than creating a user-defined function to display a copyright message, you might create a custom tag or a template. Also rather than developing several related user-defined functions to perform similar operations on the same piece of data, you can create a ColdFusion component.The benefit of using a component in this case is that the shared data can persist through several function calls.
218
Chapter 16
User-Defined Functions
16.1. Declaring a Function You want to define a simple function.
Technique Use the tag to define a user-defined function. Use to return a value from the function. You Are using Microsoft Internet Explorer! You Are not using Microsoft Internet Explorer!
Comments This example created a user-defined function that returns true if the client browser is Microsoft Internet Explorer and false otherwise. The tag tells ColdFusion that you are declaring a function; inside the tag resides the CFML code that is executed when the function is called. has several attributes but only name is required.The name attribute, as you might expect, defines the name you use to call your user-defined function. Just like variable names in ColdFusion, function names are not case sensitive. Function names follow the same rules as variable names; the only limitation is that you cannot define a function with the same name as an existing function (both built-in, and user-defined functions). Although name is the only required attribute, it’s a good idea to use the returntype attribute. If your UDF does not return anything, you can set returntype equal to void.The return type can also be set to any of the values listed in Table 16.1. Table 16.1 Function Data Types Return Type
Meaning
string
Covers all simple variables such as numbers, booleans, and lists, as well as plain text strings. A string or number that can be reduced to true or false.
boolean
16.1.
Declaring a Function
Table 16.1 Continued Return Type numeric struct query variableName void array date binary any guid uuid componentName
Meaning Any string that can be evaluated as a number. A ColdFusion structure. A ColdFusion query object. Any string that matches the rules for a ColdFusion variable name (no spaces, and so on). The function does not return a value. A ColdFusion array. A ColdFusion date object. Binary data. Anything; this is the default. A globally unique identifier. A universally unique identifier. The name of any ColdFusion component.
Table 16.2 contains a complete listing of the attributes for the tag. Table 16.2 Tag Attributes Attribute
Meaning
name
The name of the function; required. The data type that the function will return, see Table 16.1 for possible values. Required when implementing a Web service, and highly recommended otherwise. When set to true, the contents of the tag are effectively wrapped with a tag.When false, wraps the content with a tag. Note the ColdFusion documentation specifies that this attribute only works when is used in a ColdFusion component; however, we have found it to work for UDFs as well. A list of role names that have permission to execute the function. See Chapter 13, “User Authentication and Authorization,” for more information on roles. Used in components; valid values are private, public, package, and remote. See Chapter 19 for more information. A string that describes the function; used only in ColdFusion components.
returntype
output
roles
access hint
When you have a result to return from the function, you use the tag. Returning variables is described in detail in section 3 of this chapter. How do you call a UDF? By its name of course. UDFs are called just like you do a built-in ColdFusion function such as IsDefined() or Len().
219
220
Chapter 16
User-Defined Functions
16.2.
Function Arguments
You want to pass an input value to your function.
Technique Use the tag to define function arguments.
Comments The tag allows you to define not only the name of an argument, but also its data type, default values, and an option to specify whether the argument is required. Because you cannot specify such options with UDFs in , this is one of the reasons it’s good to use the syntax.The attributes for the tag are defined in Table 16.3. Table 16.3 Tag Attributes Return Type
Meaning
name
The name of the argument; required. The data type that the input value must be; see Table 16.2 for possible values. This value defaults to any, but is highly recommended. If true, the argument must be present when the function is called. If false, the attribute can be omitted. The value to use when the argument was not passed into the function.
type required default
16.2.
Function Arguments
The example Split function takes a string, and optionally a size, and returns an array of substrings that are of the size specified.The size argument is not required and the default size is 5, so when you call the split with the string 1234567890, it returns an array with two elements the first 012345 and the second 67890. As you might have assumed, the order of tags is important.The order that the tags show up is the same as the order that arguments are used in the UDF call. The value of an argument can be accessed using structure dot notation (arguments.argumentName), and also as an array. Using arguments as an array allows you to write functions that take in an unknown number of arguments.The following code shows the Split function illustrating this point:
The SuperSplit function allows you to pass in multiple lengths at which to split the string.This example passes in a phone number, 555-555-1234, and the lengths 3, 1, 3, 1, and 4.The result is an array with elements 555, -, 555, -, and 1234.This function would allow you to easily reformat the phone number or any other data that is stored in a known format.
221
222
Chapter 16
User-Defined Functions
16.3. Returning Values You want the function to return a value.
Technique Use the tag to return a result from a user-defined function.
You Are using Microsoft Internet Explorer! You Are not using Microsoft Internet Explorer!
Comments This version of the IsIE function does the same thing as the version presented in section 1 of this chapter; however, the code used to implement it is much shorter.The tag can take any expression or variable and return it to the function’s caller. In IsIE, you can use the expression CGI.USER_AGENT contains “MSIE” inside the tag because its result is effectively the intended result of the IsIE UDF.
16.4. Suppressing Output You want to suppress output in your custom function from appearing in your response.
Technique Use the output attribute of the tag to control output generated by the function. #x#
Comments This example defines three functions, all with the same body, yet each function outputs a different result.The difference in each function is the value or presence of the output attribute. Let’s explore what each function yields. The first function, noOutputAttribute, doesn’t specify a value for the output attribute in the tag. The body of the function is executed just as you might expect; it simply prints the string #x# because you didn’t place the tag around the variable. The next function, outputTrue, sets the output attribute to a value of true.The output of this function is Value.When output is true, the tag automatically wraps a around the body of the function, thus allowing variables to be evaluated. The third function does not produce any output because output is false.When output=”false”, wraps the function body with tags to suppress output. Note that all these functions specify a return type of “void”, meaning they don’t return anything. However, they can output a value to the response. Because functions can both output a value and return a value, it’s best to always use output=”false”, and stick to custom tags or CFML templates for generating output.
16.5. Recursive Functions You want to write a function that calls itself.
Technique Make a call to the function from within the function.
223
224
Chapter 16
User-Defined Functions
23 = #Power(2,3)#
Comments This example defines a function called Power that can be used to calculate the value of a base number raised to an exponent. For example, to calculate two cubed (23), two is passed in as the base, and three is passed as the exponent.The value is calculated by multiplying 2 * 2 * 2 or by multiplying 22 * 21 * 20. The first step to creating a recursive function is to find the base case.The base case is a simple sub-problem that you can solve.This problem has two potential base cases; you know that x1 is always x, and that x0 is always 1.This algorithm uses x0 as the base case. Next, you need to define the recursive step.This step keeps recursively calling itself with different values until the base case is reached. In the Power function, this is achieved by decrementing the exponent and calling the Power function again. Like many recursive problems, this problem can be solved iteratively as follows: 23 = #Power(2,3)#
16.6.
Working with Function References
Although many recursive problems are difficult to convert to iterative ones, this one was fairly easy. Recursion is typically used because the recursive solution to a problem is easier to find than an iterative one. Iterative solutions typically perform better than recursive solutions due to the overhead of calling a function over and over.The build up of this overhead can often lead to a common problem when using recursive functions, called a stack overflow. Each time you call a function, the function call is placed on the call stack. As you might imagine, when a recursive function is calling itself thousands of times, this call stack can fill up quickly. One solution to this problem in many languages is to create a function that is tail recursive, meaning the last line in the function is the recursive step (the recursive Power function is tail recursive).Tail recursive functions can be removed from the stack after they are called, thus avoiding a stack overflow. In ColdFusion, tail recursive functions can still cause a stack overflow, so be careful. Try running the recursive Power function with a very large exponent; ColdFusion will report the stack overflow.
16.6. Working with Function References You want to store a reference to a function in a variable.
Technique Set a variable to the name of a user defined function. We are using Internet Explorer We are not using Internet Explorer
Comments When you define a function, a local variable is created using the name of the function. The variable holds a reference to the function.The function reference can be assigned to another variable. In this example, the IsIE function was defined and a reference to the IsIE function is copied to the variable ie in this line:
225
226
Chapter 16
User-Defined Functions
When function references are copied to different variables, they are copied by reference, not by value.When a variable is copied by value, an entire copy of the object is copied; when a variable is copied by reference, only a reference (an indicator to the original object’s location) to the object is copied.This point is illustrated in the following example: #reference()# #reference()# #reference()# #B()#
This example outputs the following: A B B A
The crux of this example occurs when a reference to the function A is copied to the variable B.
The resulting output shows two things. First it shows that the variable B is simply a reference to the function B and not the function itself. Second it shows that the variables are copied by reference and not by value, because the third line of output displays a B and not an A. References to user defined functions can be stored in different scopes such as application, server, session, and so fourth. However, when a function is defined it must not have a dot (.) in its name.The following code will throw an exception:
16.6.
Working with Function References
The proper way to store a reference to a function in a scope other than the default (the variable’s scope) is to copy the reference as follows:
227
17 ColdFusion Custom Tags
17.0.
Introduction
Good programming languages should encourage code isolation and encapsulation. By dissecting your application into small, highly specialized pieces, you can make it easier to maintain, extend, and debug. ColdFusion custom tags are the oldest means to encapsulate code in the CFML programming language. Prior to ColdFusion 5.0, custom tags provided the best (and, for the most part, only) way to group common logic into a reusable code component. Newer versions of ColdFusion have added other extensibility mechanisms. ColdFusion 5.0 introduced custom functions to the CFML language and ColdFusion MX includes support for ColdFusion Components (see Chapter 19, “Components”). Despite these advances in CFML, scripted ColdFusion custom tags are the simplest and most versatile way to create application building blocks.This chapter explores ColdFusion custom tags.You’ll write some tags and look at how these tags can be used within client templates.You’ll also look at topics such as data exchange and the nesting of custom tags.
17.1. Creating a Simple Custom Tag You want to create a simple custom tag.
Technique Create a custom tag by creating a regular ColdFusion template called helloWorldTag.cfm: Hello World!
230
Chapter 17
ColdFusion Custom Tags
Comments Any ColdFusion template can be treated as a custom tag.There is no limit to the functionality that your custom tag can implement.The example here shows the simplest of ColdFusion templates; the template merely outputs the string “Hello World!”. This template can be used as a custom tag if it is placed in the CustomTags folder in the ColdFusion installation directory or in the same directory as the calling template. The tag created in the previous example is called helloWorldTag.
17.2. Accessing a Custom Tag You want to access an existing custom tag from your ColdFusion application.
Technique Execute a custom tag by using the call syntax. Calling the HelloWorld custom tag...
Comments The template in this example acts as a client to the HelloWorldTag custom tag. Note that you must use the cf_ prefix when calling any custom tag.The result of invoking the HelloWorldTag custom tag is the insertion of the string “Hello World” into the calling template.
17.3.
Using Attributes
You want to pass CFML data structures to your custom tag.
Technique Use the Attributes structure to pass arguments to a custom tag. greetingTag.cfm: Hello, #Attributes.name#
Comments Attributes are the best way to communicate with your custom tag. In theory, a custom tag can use the Caller variable scope to look for variables.This is not good style, though, because it creates a tight coupling between the client and the custom tag and inhibits the tag’s reuse in other applications. Using attributes in your custom tag is extremely simple. ColdFusion creates an implicit Attributes collection that your custom tag can query to find and extract mandatory and/or optional attributes. In the file greetingTag.cfm, the custom tag uses the tag to initialize the optional name attribute. It is a good idea to use the tag to identify all of the custom tag’s mandatory and/or optional attributes. Declare mandatory attributes by using the tag without the default option to cause ColdFusion to throw an error if the user fails to specify the attribute. All optional attributes should be initialized with to some default value, such as the empty string. Attributes can subsequently be referenced in the custom tag template by using the Attributes prefix. Passing attributes from a client to a custom tag is even easier. All you need to do is specify the attribute name and value in the custom tag reference. For example, the template greetingClient.cfm calls the custom tag and passes in the name attribute with the following line of code:
17.4. Returning a Result You want to return a result from your custom tag.
Technique getDomainTag.cfm:
231
232
Chapter 17
ColdFusion Custom Tags
result = GetToken(Attributes.email,2,”@”); SetVariable(“Caller.”&Attributes.name,result);
getDomainClient.cfm: The domain for the email address #email# is #domain#.
Comments Most custom tags are not meant to output content. Usually, a custom tag performs an operation and returns the result to the calling template.The calling template can choose to display the result, or not.This practice was particularly common before custom functions were released in ColdFusion 5.0. A common design pattern for returning results is the addition of a required “name” or “variable” attribute to the custom tag.This variable contains the name of a variable in the Caller scope where the custom tag should place its return result. Any ColdFusion programmer who has used the tag should recognize this concept.
17.5. Adding Start and End Tags Your custom tag requires a body.
Technique biu.cfm:
biuClient.cfm:
17.5.
Adding Start and End Tags
The following text has been formatted by the biu custom tag... Today’s date is #DateFormat(Now(),’mm/dd/yyyy’)#.
Comments ColdFusion Custom Tags can have both a start and an end tag.This feature enables you to perform operations on the content between the start and end tags. In such cases, ColdFusion will call the custom tag twice—once when it encounters the start tag and again when it encounters the end tag. ColdFusion creates an implicit ThisTag structure that contains four variables to help the custom tag determine its context.Table 17.1 shows the contents of the ThisTag structure. Table 17.1 ThisTag Variable Contents Key
Value
AssocAttribs
An array of attributes contained in associated nested tags. Indicates whether the tag has been called in reference to the start tag or end tag.Values are start or end. The evaluated form of all content that has been embedded within the start and end tags.The custom tag can change this variable, affecting its own output. A Boolean that indicates whether the tag has an associated end tag. This variable is most often used for sanity checking. A custom tag that expects both start and end tags should throw an error if the value of HasEndTag is false.
ExecutionMode GeneratedContent
HasEndTag
Custom Tags that have both start and end tags should first check the ExecutionMode variable. If the value is start, the tag should check for mandatory and optional attributes, initializing and undefined optional attributes. If the value of the variable is end, the custom tag should implement the primary algorithm. The biu.cfm custom tag represents a significant addition to the CFML language. The tag makes all embedded content bold, italicized, and underlined.The custom tag explicitly sets its GeneratedContent variable to implement this functionality.The expression wraps any content contained within the start and end tags with the HTML , , and tags.
233
234
Chapter 17
ColdFusion Custom Tags
17.6. Building Nested Tags You want to use nested custom tags for increased flexibility.
Technique mailto.cfm:
massmailer.cfm: #ThisTag.GeneratedContent#
massmailerClient.cfm:
17.7.
Encoding Custom Tags
Message Text
Comments Nesting custom tags can be an elegant way to pass dynamic information.This approach is often more practical than specifying a long, unwieldy attribute list. ColdFusion implements nested custom tags via the CFML tag. links a child tag’s attribute list to its parent tag. By default, the child tag’s attributes are placed into the parent’s ThisTag.AssocAttribs array of structures. However, the child tag may also specify to the parent attribute where its attributes should be placed.The mailto.cfm example uses the dataCollection attribute of the tag to specify that its attribute lists are found in the variable ThisTag.addresses of the parent tag. The examples shown in this section implement a custom tag called that accepts one or more nested sub-tags.The intent of this example is to implement a wrapper for the tag (or any other mail engine) that is designed to send one email to a large recipient list. By standardizing on this custom tag, you can radically change the implementation of the underlying messaging system without disturbing its call semantics. The mailto.cfm template contains the implementation of the child tag.This tag is used to specify a single email address to which the email should be sent. The user can nest one or more of these tags within the custom tag. The logic behind the tag is straightforward; it must only associate its address attribute with the parent tag. The massmailerClient.cfm template shows how easy it is to use the tag and its associated tag.The message text can appear anywhere within the start and end tags.
17.7. Encoding Custom Tags You want to encode your tag for distribution so that others cannot see its source code.
Technique Use the cfencode.exe command to encrypt a custom tag. c:\CFusionMX\bin\cfencode.exe biu.cfm biu_encoded.cfm /h “Bold, Italicize, Underline” /v “2”
235
236
Chapter 17
ColdFusion Custom Tags
Comments You may have purchased or downloaded a prepackaged custom tag from the ColdFusion Developer’s Exchange. If so, there is a pretty good chance that the tag you downloaded is encrypted so that its source cannot be copied or modified illegally.You might wish to encode your own custom tags for distribution in a similar manner. Fortunately, ColdFusion provides a utility that you can use to encrypt your own ColdFusion templates. The cfencode.exe program, included in the bin directory of your ColdFusion distribution, is a command-line tool that reads a ColdFusion source file, encrypts it, and writes it back to disk. Once encrypted, the ColdFusion template can be deployed and executed on any ColdFusion server, but it can no longer be modified. This example uses the cfencode.exe utility to encrypt the biu.cfm custom tag. The command’s syntax is as follows: cfencode.exe infile [outfile] [/r] [/q] [/h “header”] /v “2”
Table 17.2 provides a description of the command’s arguments. Table 17.2 cfencode.exe Arguments Argument
Description
infile
Mandatory. One or more source files to encode. Optional.The name of the new file(s) to be written. Can be left blank for inplace encoding. Optional. Recursively process directories. Optional. Suppress warning messages. Optional. Include a custom header message in the encoded file. Mandatory.The encryption version number to be used.
outfile /r /q /h /v
17.8. Using You want to call a custom tag regardless of its location.
Technique
17.9.
Using
Comments The tag allows you to invoke a custom tag by explicitly stating the template to use.The tag requires you to specify the template attribute, which spells out a relative template path for the custom tag. Alternatively, you can use the tag’s name attribute to provide a dot-delimited directory path to the custom tag template, relative to the ColdFusion Custom Tags directory. For example, the command:
would execute the following template: /CustomTags/com/mycompany/util/UtilTag.cfm
Attributes can be passed to a custom tag called by in one of two ways. Individual attributes can be named by using the attribute_ naming convention. For example, the command:
would call the util.cfm template, passing in the attributes name and email. You can also use the attributeCollection attribute of the tag to communicate a custom tag’s attributes.The same custom tag can be called with the following statements:
The attributeCollection attribute will work with any custom tag that you call, even if you are calling the tag with the
Comments Before you get too far into the syntax, it’s important to examine some aspects of objectoriented programming, and understand how it relates to ColdFusion components.The best way to think about objects is to consider a physical object, for instance, a light. A light can be on or off (its property is to emit light).There also needs to be a way to turn the light on and off, a light switch—speaking programmatically, the switch is a function you can call. In object-oriented programming, you can bundle all of the functions and properties (variables) of an object into an entity. Once you’ve defined the structure of your light, in order to use it you have to instantiate it, or create an instance of it.You can create multiple light objects by using just one definition. Each light instance has its own storage for variables, so each instance can be at its own state. The Light component is created in its own file with the extension .CFC (light.cfc). The tags act as containers for defining the component. Local variables defined within the tags (such as lightIsOn) are accessible only to functions within the component; they are sometimes referred to as instance variables (because each instance of a component can have a different value stored in the variable). ColdFusion components don’t provide all of the features that most object-oriented languages provide. However, you can easily apply object-oriented design principles and patterns when designing ColdFusion components.This is why studying object-oriented design is a worthwhile task for ColdFusion developers. Note You can create variables that are accessible outside of the component by using a scope such as application or session. You can also use a special scope called this inside a CFC to make the variable accessible (for example, componentInstance.variableName). This practice might not always lead to the best design.
The fact that only functions within the component can access the local variables is a good thing.You can validate the values to ensure, for example, that a number is always above zero. Additionally, you can have instance variables that developers calling your
19.1.
Defining a Component
component cannot access.This concept is often called encapsulation, or data hiding. Encapsulation allows you to change code within the object without changing the code used to call functions on the object. For example, consider light.cfc again, now with a light bulb that dies after a few uses:
This is an example whereby the internal logic changed, but the external structure remained the same, making it very easy to deploy changes to the internal logic. The tag has some optional attributes—hint and displayname— that can be used to describe your component.The hint attribute provides a hint as to what the component does, and the displayname attribute is used to give the component a friendly name (you can use spaces).These attributes are used by the CFC explorer, the GetMetaData function, and .The GetMetaData function is covered later in section 19.6.The CFC explorer displays the structure of your component in an HTML format.The CFC explorer is invoked by simply entering the URL of the CFC in your Web browser. For security reasons, you might be asked for your RDS or ColdFusion administrator username and password before you can view the component. The tag also has the hint and displayname attributes.These attributes have the same meaning in this context, and show up in the meta data. Note Using the hint and displayname attributes in and can greatly improve the readability of your code. These attributes also generate useful documentation when components are viewed through the CFC Explorer. For these reasons, it is highly recommended that you take advantage of these optional attributes.
261
262
Chapter 19
Components
19.2 Instantiating a Component You want to create an instance of a CFC.
Technique Use CreateObject or the tag to create an instance of a CFC.
OR
Comments There are two ways to create an instance of a CFC—with the tag or with the CreateObject function. CreateObject and are both functionally equivalent.The only difference is that CreateObject can be used from within the tag. The component attribute of tag takes the name of the CFC (the filename minus .CFC).The name attribute is the name of the variable that holds a reference to the CFC.With a reference to the CFC, you can invoke functions on it. To instantiate a component with the CreateObject function, you pass in the string “component” as the type of object in the first argument (you can use CreateObject and to create several types of objects such as Java, COM, and CORBA). In the second attribute, name, you pass the name of the CFC. The technique in this section uses the light.cfc file created in the previous technique.The code in this technique should reside in the same directory as the light.cfc file.You can call CFCs that are stored in other directories, but doing so requires a slightly different technique (see section 19.5 of this chapter for an explanation). Once you have a component instance, you can pass the instance to different functions or CFCs.You can also store a reference to a CFC instance in several scopes. The following example uses an application scoped variable to allow the CFC to persist between page requests.When a user clicks the Click Switch button, the switch method is invoked on the light component (method invocation is covered in the next section).
19.3.
Invoking a Component Method
The light is currently: On Off
19.3. Invoking a Component Method You want to invoke methods on a CFC.
Technique Use dot notation or the tag to call a method on a CFC. #counterInstance.increment()# #counterInstance.increment()# #result# #result#
Here’s counter.cfc:
263
264
Chapter 19
Components
Comments There are four ways to invoke a method (functions in an object are often called methods) in a CFC.The first way requires an instance of a CFC, the other three ways involve using an instance or creating a new instance. The first approach for invoking a method is using dot notation on an instance of a CFC.You use the syntax cfcInstanceName.methodName(arguments).The advantages to this approach are that it takes the least amount of code and works within tags. The next two approaches use the tag to invoke the method. Depending on whether you pass in CFC instance or a component name to the component attribute of the tag, the result can be different. If you pass in a CFC instance, the values stored in the instance variables (theCounter in this example) are retained. If you pass in a component name to the component attribute, a new instance of the CFC is created.When a new instance of a CFC is created, the instance variable theCounter is reset to zero.The output of the code in this technique is as follows: 1 2 3 1
Notice that the last line is reset to one, because you created a new instance of the component. If a component method has arguments that must be passed, there are two ways to achieve this with .The first way is to simply pass attributes with the same name as the arguments in to the tag. For example:
The second way to pass arguments to a component method involves a child tag of called .The tag has two attributes; name and value.The name attribute is used to identify the name of the argument, and the value attribute is used to pass the variable value to the function.
Another way to pass arguments in to the tag is to create a structure of arguments and then pass the structure in to the argumentcollection attribute.This fourth technique is shown here.
19.4.
Component Inheritance
19.4. Component Inheritance You want to create a new component that extends the functionality of an existing component.
Technique Use the extends attribute of the tag to create a component that inherits functionality from another component. Fred’s Email: #fred.getEmail()# Bob’s Email: #bob.getEmail()# Is Bob Fred’s Manager? #YesNoFormat( bob.manages( fred.getEmployeeID() ) )#
Here’s employee.cfc:
265
266
Chapter 19
Components
Here’s manager.cfc:
Comments Objects that have an “is a” relationship (a tree is a plant) are prime candidates for inheritance.This technique uses the example: a Manager is an Employee.The Manager possesses all of the properties that a regular Employee does, but also has a list of employees that he or she manages as an additional property. The Manager CFC does not need to redefine the getEmployeeID, getName, or getEmail functions; these function definitions are inherited from the Employee CFC. This is facilitated by adding extends=”Employee” to the tag in the Manager CFC. Using inheritance often reduces the amount of code you need to write, because you can inherit code from other components. Because inheritance usually saves you quite a bit of code, it is tempting to use inheritance on relationships that don’t make sense. For instance, you might try to inherit Cat from Dog because they both have four legs. Don’t use inheritance unless you can say “object A is an object B.” You may have noticed that the example defined the init function in both the Employee and Manager CFCs.The implementation of the init function in the Manager CFC is said to “override” that of the Employee CFC.The Manager CFC includes an argument for the list of employees that the manager manages.
19.5.
Accessing a Component
Another tempting practice with inheritance is to use multiple inheritance; that is object A inherits from object B and object C, but objects B and C do not inherit from each other. Multiple inheritance exists in some languages such as C++, but is not allowed in ColdFusion or Java. You can, however, inherit from multiple components one at a time. For example, object A inherits from object B, which inherits from object C. In fact, by default, all components inherit from a component named WEB-INF.cftags.component, which is the base of all components. One of the advantages of inheritance is that it allows developers to create APIs and frameworks that can be extended by other developers.The extended components then work seamlessly with the APIs. After all, when you use inheritance, your extended component is a form of its parent component. In other words, you can write a function that expects to receive an Employee and pass it a Manager.The function can also handle any component that inherits from Employee.This phenomenon is known as polymorphism in object-oriented programming circles. Note Because ColdFusion components support function overriding, but do not support function overloading (multiple function definitions with different arguments), it’s possible to override a function and change the arguments so that the child class breaks polymorphic code. The init function in the Manager CFC adds an argument, but because it designates the argument as not required, the function is still safe.
19.5. Accessing a Component You want to access CFCs from multiple directories.
Technique #light.isLightOn()#
Comments If you try to run a component in a directory other than the one it was defined in, you will find that a NoSuchTemplateException is thrown. Components can be accessed from any ColdFusion template on your server as long as you fully qualify the component name. The code in this technique instantiates a component named cfcookbook.19.light.When ColdFusion is given this component name, it looks under the Web root for the following file /cfcookbook/19/light.cfc. ColdFusion barrows some naming conventions here from Java; the directory /cfcookbook/19/
267
268
Chapter 19
Components
translates to a package named cfcookbook.19. Each directory under the Web root is its own package. ColdFusion components also allow you to enable access to functions with the access attribute of the tag. Functions defined within a component with the attribute access=”package” can only be accessed by CFCs or templates in the same package (directory). In addition, you can use access=”private” to write convenience functions that are available only to the CFC that defined them.
19.6. Using Component Meta Data You want to retrieve information about a component’s methods and properties.
Technique Pass a component reference into the GetMetaData function and manipulate the resulting structure.
Comments The GetMetaData function can be useful for debugging or for building applications that dynamically choose which methods to execute on a CFC by using the meta data. This process is often referred to as introspection. GetMetaData takes one argument, a reference to a component.You can obtain a reference to a component by using one of the methods mentioned in section 19.2 of this chapter, or by using the this keyword inside a CFC.The this keyword is a reference to the current component instance (it is also a scope that can be used to make public variables). The GetMetaData function, at a minimum, returns a structure with the following keys: extends, functions, name, path, and type.The name key stores the name of the CFC.The path key stores the path to the CFC on your server, and the type key should be set to component. The extends key contains the meta data for the base component. All components intrinsically inherit from WEB-INF.cftags.component. If you used the extends attribute to inherit from another component, it will appear in the extends key of the structure. In the functions key of the meta data structure is an array of structures, each structure has information about a function in the component.The function structure mini-
19.6.
Using Component Meta Data
mally has the keys name and parameters.The name key corresponds to the name of the function, and the parameters key holds an array of structures for each function argument.The parameters structure has keys equivalent to the possible attributes for the tag (name, returntype, default, and type).The structure in the functions array can also contain some additional keys depending the attributes present in the tag, including access, displayname, hint, roles, and returntype. The best way to work with meta data is to output the meta data structure with and then extract the pieces you need. Keep in mind that the presence of structure keys depends on which attributes were used with the , , and tags.
269
20 Objects
20.0.
Introduction
ColdFusion’s object support is perhaps one of the most underused features of ColdFusion. Using the tag, or its equivalent function CreateObject, allows you to have direct interaction with ColdFusion Components,Web services, Java, COM, or CORBA objects. Because ColdFusion Components (or CFCs) are implemented in the CFML language, an entire chapter is devoted to them (Chapter 19, “Components”).Web services are also covered in a separate chapter (Chapter 23, “Web Services”).This chapter covers the processes of creating and invoking Java, COM, and CORBA objects. Using objects liberates your ColdFusion code from performing complex business logic.The logic is instead written and optimized in a separate class. Using objects also can increase the performance and scalability of an application. For example, if the object can be distributed across multiple servers, you increase scalability. Several third-party objects and components are available that can reduce the amount of time needed to develop an application. In addition, most third-party objects undergo more testing than you would normally administer, providing better reliability and stability.
20.1. Creating a Java Object Instance You want to create an instance of a Java object within ColdFusion.
Technique Use the tag or the CreateObject function to create an instance of a Java object:
272
Chapter 20
Objects
or
Comments There are two ways to create an instance of any arbitrary Java object in ColdFusion— and CreateObject. In the tag, four attributes are required to instantiate the object—name, class, type, and action. The value of the name attribute corresponds to the name of the ColdFusion variable that holds a reference to the instantiated Java object. Using one of the persistent scopes (application, session, server, or client) allows the object instance to persist between multiple page requests. The class attribute of the tag defines the name of the Java class to be instantiated.The class must be in the server’s classpath in order for ColdFusion to find the code for the class. Several classes and packages are available natively as part of Java. Such classes can be instantiated without concern as to whether they have been added to the classpath, as they are intrinsically part of the Java platform. Some of the most useful classes that are part of the Java platform can be found in the java.util package.The java.util package contains several data structures such as List, Hash Table, Set,Tree, and a Stack (this technique instantiates a Stack object). Because the tag can also be used to instantiate ColdFusion Components,Web services, CORBA, and COM objects, the type attribute is required. The action attribute is also required.To create an instance of a Java object, set type=”java” and action=”create”.Table 20.1 lists all of the attributes of the tag. Table 20.1 Attributes Attribute
Type
Meaning
type
Java, CORBA, and COM
name class
Java, CORBA, COM, Component,Web Service Java, CORBA, and COM
action
Java, CORBA, and COM
The type of object to create: Java, CORBA, or COM. Required if the component attribute is not present. The name of a variable that will hold a reference to the object instance. Required. An identifier to the class to be instantiated. Required if the component attribute is not present. Java and CORBA always use the value create. With COM you can specify create or connect. Connect is used to connect to an existing object. Required if the component attribute is not present.
20.2.
Invoking Methods on an Object
Table 20.1 Continued Attribute context
Type CORBA and COM
server
COM only
locale
CORBA only
component Component’s only
webservice Web Service’s only
Meaning Specifies the context in which the object will be created. Possible values in CORBA are IOR or nameservice.When type=”COM” is used, the values are InProc, local, or remote. Required for CORBA; COM objects use registry settings as a default. A DNS or UNC path. Required if context=”remote”. The name of the CORBA ORB connection to use. Required if there are more than one registered connectors in the ColdFusion Administrator. The name of a ColdFusion Component to create an instance of. See Chapter 19 for more information. A URL to a WSDL file, which describes the service.
The CreateObject function can also be used to instantiate a Java object with slightly less code.The first argument of the CreateObject function corresponds to the type attribute in .The second argument represents the name of the Java class to instantiate (corresponds to the class attribute of ). CreateObject returns a reference to an instance to the Java object.This reference can then be stored in a ColdFusion variable. Although CreateObject and yield the same result, CreateObject can be used within blocks, and can be invoked with less code.
20.2. Invoking Methods on an Object You want to invoke static or instance methods on an existing object.
Technique Use the syntax instanceName.methodName(arguments) to invoke a method on an object. pop: #stack.pop()# pop: #stack.pop()#
273
274
Chapter 20
Objects
Comments The technique to invoke a method on an object is identical for each type of object that ColdFusion supports (Components, Java, CORBA, COM, and Web services). This technique invokes a method on a Java instance—namely methods on the java.util.Stack class.The stack data structure allows you to push objects onto the stack, and then pop them off the top.The first item on the stack will be the last item popped off (this is known formally as Last In First Out, or LIFO). Items are placed on the stack with the push method.The push method takes one argument of type java.lang.Object. Because all methods in Java inherit from java.lang.Object, any variable in ColdFusion MX also inherits from java.lang.Object behind the scenes.Thus you can pass any variable into the push method; however, this technique used the literal strings “A” and “B” for simplicity. Items are popped off the top of the stack with a call to the pop method. Execution of this technique outputs “B” “A” (LIFO ordering). You can also invoke static methods (methods that do not use instance variables) with ColdFusion MX. However, in ColdFusion you must still create an instance of the object before you can call a method on it, which defeats the performance benefits of using static methods.The code to invoke a static method is the equivalent to an instance method. #system.currentTimeMillis()#
Because ColdFusion MX is a loosely typed language, all numbers are represented as strings.When a ColdFusion number is passed to a Java method that expects an int as an argument, ColdFusion will convert the string representation of the number into an integer.These conversions will degrade performance. If you need to perform several Java method invocations, especially those using data types other than String, you might be better off writing a high-level wrapper class in Java. If a Java method is overloaded (it can be passed different data types), you may need to use the JavaCast function to explicitly cast a ColdFusion variable to a primitive data type.The JavaCast function takes two arguments; the first argument is the type to cast to. Possible values for this argument include int, string, boolean, long, and double.The second argument of the JavaCast function is the value you are casting.
20.4.
Working with Java Objects
20.3. Using Properties on an Object You want to access public properties on an object.
Technique Use instanceName.propertyName to read or set the value of a public property. #pi#
Comments Accessing a property in an object is identical to accessing a key within a structure using dot notation.The syntax is the same for all types of objects. The property in this example happens to be the value of PI—a static value.This property is defined as static final, which in Java means that its value cannot be changed. Because PI is read-only, you cannot write to it; however, some properties can be written to.The syntax for writing to a property is simply instanceName.propertyName = value.
20.4. Working with Java Objects You want to work with Java objects.
Technique Create an object instance with or CreateObject with type=”java”, and then call methods or properties on that object. Are you feeling lucky? #YesNoFormat(randomBool)#
Comments In ColdFusion MX, short of Components, Java objects are the natural choice for implementing business logic and utility functions. Due to its Java backbone, ColdFusion MX handles Java objects much more gracefully than it does CORBA or COM objects. Some of the shortcomings of using Java objects, or any type of object, is due to the way CreateObject and work.There is no way to call the constructor
275
276
Chapter 20
Objects
when the object is created in CreateObject or .The constructor can be called by using the init function.When ColdFusion receives a call to the init function, it calls the constructor. Although this works, it isn’t optimal because two objects are created (one in CreateObject/, and one in init).
20.5. Working with COM Objects You want to work with COM/DCOM objects.
Technique Use the tag to connect to or create an instance of a COM or DCOM object. C:\ [#drive.VolumeName#] Total Size: #Round((drive.TotalSize / 1024) / 1024)# MB Free Space: #Round((drive.FreeSpace / 1024) / 1024)# MB
Comments COM (Component Object Model) object support is found only in the Windows versions of ColdFusion MX. Being a Windows-centric technology, COM often makes it easy to interact with Windows components, such as the file system illustrated in this technique. In order for ColdFusion to get an instance of a COM object, it must first be registered.To register a DLL (Dynamic Link Library), use the regsvr32 program. For example: regsvr32 c:\file.dll
Several COM objects are installed as part of Windows, or as part of service packs such as the Scripting.FileSystemObject.These objects are already registered, and therefore should work in a ColdFusion environment without any extra steps. This technique attempts to connect to an instance of the Scripting.FileSystemObject that is already running on the server. If no instance is running, the block executes and creates a new instance of the object. With an instance to the Scripting.FileSystemObject, you can call methods or
20.6.
Working with CORBA Objects
access properties exposed by the object. In this case, you call the GetDrive method to retrieve an object with information about the specified drive. COM object performance has degraded significantly in ColdFusion MX. Because ColdFusion MX is written in Java, it requires a Java-to-COM bridge to facilitate the communication. ColdFusion MX currently uses a third-party Java-to-COM bridge called Jintegra. One of Macromedia’s recommendations to improve performance is to create a Java stub for your COM object.The Java stub is effectively a Java wrapper for the COM object. A tool that is part of Jintegra, called com2java.exe, automatically generates the Java stub.You can find out more information about this technique in Macromedia’s Technote #22922. Rather than waiting for patches and performance tweaks, a good long-term solution is to rewrite your COM objects in Java. Besides increased performance, you will also have an operating system-independent application. You can connect to objects on your network using DCOM (Distributed Component Object Model) by specifying the server attribute in .The server attribute must contain a DNS name (such as www.server.com), an IP address, or a UNC name (such as \\computer). The CreateObject function can also be used to connect to or create a COM object instance, as in this example code:
20.6. Working with CORBA Objects You want to work with CORBA objects.
Technique Use or CreateObject to create an instance of a CORBA object. #person.getName()#
Comments Common Object Request Broker Architecture, or CORBA, is a mechanism for developing language-independent distributed applications.The specifications for CORBA are managed by the OMG (Object Management Group). CORBA implementations exist for nearly every object-oriented language. CORBA achieves its language independence by using its own language to describe the object interface.The language is called IDL (Interface Definition Language). Using the IDL for verification, all object invocations are passed through an ORB (Object Request Broker).The ORB is responsible for finding and managing a connection to the Servant object (the implementation of the object). Servant objects are classes written in a CORBA supported language, and typically bound to CORBA through stub classes. Because all requests go through the ORB, the server and the ORB can reside on different computers, allowing for the construction of distributed applications. ColdFusion MX is integrated with Borland VisiBroker 4.5.1 for Java ORB; however, you must download and install VisiBroker from Borland if you want to use CORBA with ColdFusion MX. Once installed, you have to set up a CORBA connector in the ColdFusion Administrator.The ColdFusion MX documentation details the necessary installation steps. Note Other ORBs can also be used with ColdFusion MX; however, you must write a connector for the ORB vendor. Contact Macromedia if you need to use an ORB other than VisiBroker.
Once a connection to the ORB is present, the ORB must be able to find the Servant objects you want to invoke.There are two supported methods for facilitating this— Naming Services and Interoperable Object References (IOR).The previous code example uses a file that contains the IOR; the filename is passed through the class attribute of .The context attribute is used to distinguish between using an IOR and a CORBA naming service.The following example shows using a naming service:
The class attribute when context=”NameService” contains the name of the object; forward slashes (/) are used as delimiters. An additional attribute of is provided to specify which CORBA connector you are using. If you have multiple ORBs registered in the ColdFusion administrator, you need to pass the name of the connection into the locale attribute of . For example, to connect to an ORB called JavaIDL, you use the following code:
20.6.
Working with CORBA Objects
The CreateObject function can also be used to retrieve object handles from the ORB.
The CreateObject function expects the arguments type, context, class, and optionally locale. The mapping of IDL to ColdFusion is defined in Table 20.2. Table 20.2 CORBA IDL to ColdFusion Type Mappings IDL Type
ColdFusion Type
any
No Yes Object reference Yes Boolean Yes String Yes N/A No Numeric Yes Numeric (zero is the first number in the enumeration) Yes Numeric Yes Object reference Yes Numeric Yes N/A No N/A Yes String Yes Array Yes Numeric Yes String Yes Structure Yes N/A Yes N/A No Number Yes N/A No Number Yes
array attribute boolean char constant couble enum float interface long longlong module octet sequence short string struct typedef union unsigned long unsigned longlong unsigned short
N/A
Array
Supported
279
280
Chapter 20
Objects
Table 20.2 Continued IDL Type void
ColdFusion Type N/A
wchar wstring
String String
Supported Yes Yes Yes
Some of the goals of CORBA are very similar to the goals of Web services, such as distributed language-independent objects.Web services are much easier to use in ColdFusion MX than CORBA, and may be a better choice. See Chapter 23, “Web Services,” for more information about Web services.
21 WDDX
21.0.
Introduction
Web Distributed Data Exchange or WDDX is an XML format for serializing data structures (such as structures, arrays, and queries/recordsets) and data types (such as strings, numbers, booleans, and binary).WDDX was introduced in ColdFusion 4.0 with hopes to promote language-independent data sharing. Several toolkits have been developed for WDDX in languages other than ColdFusion, such as ASP, Java, JavaScript, Perl, PHP, and C#. However,WDDX has yet to reach widespread adoption outside of the ColdFusion community. WDDX is a good shortcut for converting ColdFusion variables into XML documents.The tag also makes it easy to represent ColdFusion variables as JavaScript variables.
21.1. CFML to WDDX You want to convert a CFML data structure into a WDDX XML document.
Technique Use the tag with action=”CFML2WDDX” to convert a ColdFusion structure to WDDX. #HTMLEditFormat(skiWDDX)#
282
Chapter 21
WDDX
Comments The code in this technique creates a simple array with two elements, and represents the array in a standard XML format,WDDX.The following code shows the generated XML, or WDDX packet, stored in the skiWDDX variable. WhiteFace Killington
The generated XML produces enough information for any language to reconstruct this ColdFusion array in its native array. The key element of this example is the tag, as it does the work of converting the ColdFusion variable into XML.The action attribute of the tag specifies the type of translation to be performed.The action in this case is CFML2WDDX. The other three possible values for action are discussed in subsequent sections of this chapter. When you specify action=”CFML2WDDX”, the tag will naturally convert the input variable (identified by the input attribute) into a WDDX packet.The result of the operation is stored in the variable name designated by the value of the output attribute.Table 21.1 shows some common tag attributes. Table 21.1 Tag Attributes Attribute
Meaning
action
The type of WDDX translation to perform. Possible values are CFML2WDDX, WDDX2CFML, CFML2JS, and WDDX2JS. Input value to serialize or deserialize. Name of a variable to store the result of the action. If the action generates JavaScript (if action is CFML2JS or WDDX2JS), and this attribute is not present, the result will print to the page output stream. When true, validates input WDDX against the WDDX DTD. Used with the actions WDDX2CFML and WDDX2JS. The JavaScript variable name for the resulting JavaScript object. Only used when action is CFML2JS or WDDX2JS. When set to true, represents times in the ISO8601 format.When it’s false, local times are used.
input output
validate toplevelvariable usetimezoneinfo
21.2.
CFML to JavaScript
This example uses the HTMLEditFormat function to format the XML so that it will display in your browser (it escapes the < and > characters).This is handy for displaying WDDX. Some Web browsers will format XML in an easy-to-read format.You can let the browser know that your returning XML by setting the HTTP response header Content-Type to text/xml. HTTP response headers can be issued with the tag. #skiWDDX#
In Internet Explorer, the XML is presented in a color-coded format with collapsible nodes instead of in HTML format.
21.2. CFML to JavaScript You want to convert a CFML data structure into a JavaScript object.
Technique To convert a ColdFusion data structure to a JavaScript object, you use the tag with the action attribute set to CFML2JS.
if (jsTrail[“isopen”] == “true”) { alert(“Trail: “ + jsTrail[“name”] + “ is open.”); } else { alert (“Trail: “ + jsTrail[“name”] + “ opens on “ + jsTrail[“opens”]); }
Comments Converting from CFML to JavaScript doesn’t actually involve WDDX.The ColdFusion variable is converted to a JavaScript variable with the tag. In this technique, the tag produces the following JavaScript code:
283
284
Chapter 21
WDDX
jsTrail = new Object(); jsTrail[“opens”] = new Date(2002, 10, 1, 0, 0, 0); jsTrail[“isopen”] = “false”; jsTrail[“name”] = “BarkEater”;
There are a few things to note about the generated JavaScript code.The isOpen key in the trail structure is converted to lowercase; this is important because JavaScript variables are case-sensitive, but ColdFusion variables are not. Attempting to read the JavaScript variable jsTrail[“isOpen”] will return a null value. The ColdFusion variable trail.isOpen is set to a boolean value, false. However the corresponding JavaScript variable jsTrail[“open”] is set to the string “false”, not a boolean. Because of this, you can’t treat the JavaScript variable as a boolean. For example if (jsTrail[“isopen”]) will never evaluate to true, even if trail.isOpen is set to true. One feature of the generated JavaScript is that ColdFusion date objects are converted into JavaScript date objects, as the value of jsTrail[“opens”] illustrates. Different ColdFusion data types generate different JavaScript objects.Table 21.2 shows some common JavaScript conversions. Table 21.2 CFML2JS Conversions Data Type CFML
Note If you want to work with query objects in JavaScript, you need to include the WDDX JavaScript library. The definition for the WddxRecordset JavaScript object is defined in this library, along with a JavaScript to WDDX serializer. Binary data also requires the JavaScript WddxBinary object to be defined. To include the library, use the src attribute of the tag—.
21.3.
WDDX to CFML
21.3. WDDX to CFML You want to convert a valid WDDX XML document into a CFML data structure.
Technique Use action=”WDDX2CFML” in the tag to convert WDDX to a ColdFusion variable. WhiteFace Killington #slopes[1]#
Comments The process of converting WDDX into ColdFusion data structures is known as deserialization.This code is essentially the opposite of the serialization example shown in section 21.1.The input attribute receives a WDDX string, and the output attribute holds the name of the resulting ColdFusion variable. Table 21.3 shows some common data types that are supported, and their WDDX representations. Table 21.3 WDDX Representations of Data Types Data Type
WDDX Representation
Array
One
Date Query
2000-1-1T12:0:0-5:0 value
String Structure
some string Value
Number Boolean Binary
8 YmluYXJ5
Note Binary data in WDDX is encoded in Base64 encoding.
21.4. WDDX to JavaScript You want to convert WDDX into a JavaScript object.
Technique Use WDDX2JS as the value for the action attribute in to convert a WDDX string into JavaScript variables. WhiteFace Killington
21.5.
Syndicating Content with WDDX
for (var i=0;i
309
310
CHAPTER 23
Web Services
Comments Web services built with ColdFusion can return custom data types, represented by a CFC using tags.The tag is used to describe property names and data types. By specifying multiple properties within a component, you can create your own data type.This technique creates a data type called Flight that stores information about a flight. Properties can be accessed with dot notation, as shown in the findFlight method of the TravelService CFC. Although you can simply return a structure of values, using properties is a better approach. Properties allow you to return a data structure with documented elements and data types. Structures can represent different data types and a variable number of elements. The findFlight method in the TravelService Web service returns a Flight object. In WSDL, the structure of the Flight Component is defined in XML schema as follows.
When other platforms receive the Flight object, they use this description to map data types to property names.The struct and query ColdFusion data types map to their own complexType depending on the contents of the variable.The data type mappings are defined in Table 23.1. Table 23.1 ColdFusion WSDL Type Mappings ColdFusion Type
WSDL Type
string
xsd:string or SOAP-ENC:string
numeric
SOAP-ENC:double
23.6.
Deploying a Web Service
Table 23.1 Continued ColdFusion Type
WSDL Type
date
xsd:dateTime
boolean
SOAP-ENC:boolean
array
SOAP-ENC:array
binary
xsd:base64Binary
struct query
complexType complexType
23.5. Deploying a Web Service You want to deploy a Web service on a ColdFusion application server.
Technique Add ?wsdl to the end of the URL pointing to a CFC to generate a WSDL file. #dog.getDogYears(8)#
Comments Deploying Web services in ColdFusion is very simple.The WSDL can be automatically generated by appending ?wsdl to the end of a URL pointing to the Web service CFC. Sometimes it makes sense to modify the WSDL generated by ColdFusion to use stronger typing. For instance, you might want to change SOAP-ENC:double to SOAP-ENC:integer if your Web service doesn’t use decimal points.You might also want to add typing to an array; ColdFusion arrays do not require that all elements be of the same type, yet many languages do. Changes to the WSDL can increase the performance, and possibly the interoperability, when communicating with other languages. Note If you modify the WSDL generated by ColdFusion, it is up to your application to ensure that the types returned from your application meet the specifications defined in the WSDL. WSDL is a contract that the Web service must adhere to.
311
312
CHAPTER 23
Web Services
23.6. Invoking a Web Service with .NET You want to call a Web service written in ColdFusion with the .NET platform.
Technique Use Visual Studio .NET. Here is getDogYears.aspx: Dog Service C# Client Dog Service C# Client Enter a value in person years: 0) {%> person years equals dog years
Here is getDogYears.aspx.cs: using System; using System.Web.UI.WebControls; using System.Web.UI.HtmlControls; namespace DogServiceClient { /// /// consumes the getDogYears Web Service /// public class getDogYears : System.Web.UI.Page { protected HtmlInputButton Submit1; protected TextBox TextBox1; protected double dogYears = 0; protected double personYears = 0; private void Page_Load(object sender, System.EventArgs e) {}
23.6.
Invoking a Web Service with .NET
#region Web Form Designer generated code override protected void OnInit(EventArgs e) { InitializeComponent(); base.OnInit(e); } /// /// Required method for Designer support - do not modify /// the contents of this method with the code editor. /// private void InitializeComponent() { this.Submit1.ServerClick += new System.EventHandler(this.Submit1_ServerClick); this.Load += new System.EventHandler(this.Page_Load); } #endregion private void Submit1_ServerClick(object sender, System.EventArgs e) { personYears = double.Parse(TextBox1.Text); localhost.DogServiceService svc = new localhost.DogServiceService(); dogYears = svc.getDogYears(personYears); } } }
Comments Invoking a ColdFusion Web service in the .NET environment is a relatively simple process when using Microsoft Visual Studio .NET.This example invokes the DogService.cfc Web service (defined in section 3) from a .NET Web application. The first step in accessing a Web service is to add a Web Reference to your Visual Studio project. Do this by right-clicking References in the Solution Explorer, and selecting Add Web Reference. A dialog box prompts you for the address to the Web service. In this case, you use http://localhost:8500/DogService.cfc?wsdl, which is the location of the WSDL file describing the DogService.Visual Studio generates a stub object from the WSDL called DogServiceService, in the DogServiceClient. localhost namespace shown next. Here is Web References\localhost\Reference.cs: namespace DogServiceClient.localhost { using System.Diagnostics; using System.Xml.Serialization; using System; using System.Web.Services.Protocols; using System.ComponentModel;
313
314
CHAPTER 23
Web Services
using System.Web.Services; [System.Diagnostics.DebuggerStepThroughAttribute()] [System.ComponentModel.DesignerCategoryAttribute(“code”)] [System.Web.Services.WebServiceBindingAttribute( Name=”DogService.cfcSoapBinding”, Namespace=”http://DefaultNamespace”)] public class DogServiceService : System.Web.Services.Protocols.SoapHttpClientProtocol { public DogServiceService() { this.Url = “http://localhost:8500/DogService.cfc”; } [System.Web.Services.Protocols.SoapRpcMethodAttribute(“”, RequestNamespace=”http://DefaultNamespace”, ResponseNamespace=”http://DefaultNamespace”)] [return: System.Xml.Serialization.SoapElementAttribute(“return”)] public System.Double getDogYears(System.Double years) { object[] results = this.Invoke(“getDogYears”, new object[] {years}); return ((System.Double)(results[0])); } public System.IAsyncResult BegingetDogYears(System.Double years, System.AsyncCallback callback, object asyncState) { return this.BeginInvoke(“getDogYears”, new object[] {years}, callback, asyncState); } public System.Double EndgetDogYears(System.IAsyncResult asyncResult) { object[] results = this.EndInvoke(asyncResult); return ((System.Double)(results[0])); } } }
In the codebehind file, getDogYears.aspx.cs, the DogServiceService class is instantiated and the getDogYears method is called using the instance reference—the variable svc.The result of the getDogYears method is stored in the variable dogYears.The value of dogYears, if greater than zero, is displayed in the getDogYears.aspx page.
23.7.
Invoking a Web Service with Java
23.7. Invoking a Web Service with Java You want to call a Web service written in ColdFusion with Java.
Technique Use the Apache AXIS WSDL2Java tool to create a Java stub, and then use the stub to invoke the remote method. import dogservice.*; public class DogServiceClient { public static final void main(String[] args) throws Exception { Double humanYears = new Double(8); Double dogYears = null; dogservice.DogService binding; binding = new dogservice.DogServiceServiceLocator().getDogServiceCfc(); dogYears = binding.getDogYears(humanYears); System.out.println(“Response from DogService = “ + dogYears); } }
Comments Apache Axis is an open source project for implementing and invoking Web services using SOAP with Java. Macromedia is a contributor to the Axis project, and ColdFusion MX’s Web services infrastructure is built with Axis. This example uses DogService.cfc defined in section 3 and requires Apache Axis. You can download Axis at xml.apache.org/axis/; these examples were created with Axis version 1.0. The easiest way to invoke a Web service in Java using Axis is with the WSDL2Java utility that comes with Axis.You can run the WSDL2Java tool from your command line as follows: java org.apache.axis.wsdl.Wsdl2Java http://x/y.wsdl
315
316
CHAPTER 23
Web Services
The tool can also run via an Apache Ant script. Ant is a build tool for Java (download it at ant.apache.org).The following segment of code runs WSDL2Java within an Ant target:
Both methods of running the WSDL2Java tool require the contents of the Axis’s lib directory, and a JAXP compliant XML parser to be included in the Java classpath. When WSDL2Java executes, it generates several Java source files that can be used to invoke the Web service.The two files you will use directly are the DogService interface and the DogServiceLocator class.The DogService interface simply defines the structure of the public methods in your Web service.The interface that Axis generates is as follows: public interface DogService extends java.rmi.Remote { public java.lang.Double getDogYears(java.lang.Double years) throws java.rmi.RemoteException, dogservice.CFCInvocationException; }
The getDogServiceCfc method in the DogServiceLocator class instantiates a stub class that implements the DogService interface.
24 J2EE Interoperability
24.0.
Introduction
For years, ColdFusion thrived as a Web application server, despite the momentum that Microsoft’s ASP and Sun’s Servlet/JSP competitive technologies were gaining. ColdFusion’s tag-based syntax made it a favorite among less technical Web designers. In order to secure ColdFusion’s long-term future, Macromedia has embraced Sun’s J2EE suite of standards. Macromedia’s JRun Server is a J2EE application server and, with the MX release, the ColdFusion Server is now a J2EE application that can run on a variety of J2EE-certified application servers. The ColdFusion interpreter has been reengineered as a collection of Java Servlets. Thus, all ColdFusion MX applications are J2EE applications, albeit indirectly.This architectural decision opens entirely new Java integration possibilities to ColdFusion programmers. ColdFusion MX provides for end-to-end integration with J2EE JSPs and Servlets. Servlets and JSPs can access ColdFusion session and application state and vice versa. In addition, ColdFusion pages can include JSPs and Servlets or forward processing control to them. In addition, ColdFusion MX offers tighter integration with businesstier components, such as Enterprise Java Beans. This chapter reviews the different techniques you can use to utilize J2EE components within your ColdFusion application. It covers how to access JSPs and Servlets, how to share application state with J2EE components, and how to access Enterprise Java Beans.
318
Chapter 24 J2EE Interoperability
24.1. Redirecting to a Servlet or JSP You want to forward the ColdFusion request to a Java Servlet or JSP.
Technique Use the following CFML code fragment to perform a server-side forward to a JSP or Servlet. GetPageContext().forward(“date.jsp”);
Comments The GetPageContext() function is a new addition to the CFML language. It provides access to the ColdFusion MX PageContext object, allowing you to see and manipulate page attributes and the request and response Servlet objects. The MX PageContext object wraps the Java PageContext object and exposes two functions for you to use: forward() and include(). Use the forward() function (shown in the previous technique) to forward the processing control to a Servlet or JSP deployed on the underlying J2EE application server. You can add JSPs to the standalone version of ColdFusion MX by simply adding them to your ColdFusion project. Servlets must be declared in the web.xml file under the WEB-INF folder in the ColdFusion MX wwwroot folder. Unpacked Servlet classes must be added to the CFusionMX/wwwroot/WEB-INF/classes folder. Alternatively, JAR’ed Servlet libraries can be placed in the CFusionMX/wwwroot/WEB-INF/lib folder.You must use one of the previous methods to deploy your Servlet classes before you can access them in your ColdFusion application.
24.2. Including a Servlet or JSP You want to include a Java Servlet or JSP in the context of your ColdFusion page.
Technique Use the following CFML code fragment to perform a server-side include of a JSP or Servlet. Including a jsp... GetPageContext().include(“date.jsp”);
24.3. Accessing ColdFusion Pages from Servlets and JSPs
Comments Like the tag, the MX PageContext include() function can be used to include the output of a Servlet or JSP in a CFML page.This technique uses the function to include the output of the date.jsp JSP page.
24.3. Accessing ColdFusion Pages from Servlets and JSPs You want to access a ColdFusion page from a Servlet or JSP.
Technique factorial.cfm: #num#! = #result#
include.jsp:
Comments ColdFusion’s Servlet/JSP integration is bi-directional.This means that you can include (or forward to) a ColdFusion page directly from a Servlet or JSP.The technique used to access a CFML page from a Servlet or JSP is identical to the one used to access another Servlet or JSP.This technique uses the standard JSP tag to include the results of a ColdFusion page called factorial.cfm. Note that you can use the tag to set any parameters the ColdFusion page needs in order to operate.
319
320
Chapter 24 J2EE Interoperability
24.4. Sharing Data Between ColdFusion and Servlets/JSPs You want to share common application data with JSPs and Servlets.
public class PrintVars extends HttpServlet { protected void processRequest( HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Get POST and GET parameters PrintWriter out = response.getWriter(); out.print(“Page Parameters:”); Enumeration params = request.getParameterNames(); while (params.hasMoreElements()) { String name = (String)params.nextElement(); String value = (String)request.getParameter(name); out.print(name+” = “+value+””); } // Get Request Attributes out.print(“
”);
24.4.
Sharing Data Between ColdFusion and Servlets/JSPs
out.print(“Page Attributes:”); Enumeration attrs = request.getAttributeNames(); while (attrs.hasMoreElements()) { String name = (String)attrs.nextElement(); String value = (String)request.getAttribute(name); out.print(name+” = “+value+””); } // Get Session Variables out.print(“
Comments An exciting new feature in ColdFusion MX is the capability to share application and session state among ColdFusion pages and J2EE Servlets and JSPs.The storage mechanism for ColdFusion application state has been redesigned in MX to utilize the standard J2EE request parameters, request attributes, and HTTP session objects. This allows you to mix ColdFusion pages with Servlets and JSPs in a single application while maintaining consistent session state.Thus, you can draw upon each of the Web page development technologies when the need arises. For example, you might use ColdFusion to rapidly assemble a front-end that gathers information to be passed to a Servlet-driven back-end business method.
321
322
Chapter 24 J2EE Interoperability
In the technique shown here, ColdFusion is used to populate an assortment of session and request variables, which is subsequently inspected by a Java Servlet.The example uses the expression GetPageContext().include(“/PrintVars”) to include the PrintVars Servlet that prints the application state.The PrintVars Servlet logic is divided into three sections that handle printing the request parameters, request attributes, and session variables. Request parameters, such as URL and form variables, are available in the Parameter scope of the request object. Individual parameters can be accessed by calling the request.getParameter(parameterName) function. Likewise, you can extract ColdFusion request variables (such as the one created with the CFML statement ) with the Request.getAttribute(attributeName) function. ColdFusion session variables, however, are handled slightly differently.The ColdFusion runtime engine keeps all session state in a single Servlet session variable matching the name of the ColdFusion application.This example assigned a name to the CFML page and created a session scope for it by using the tag: . Behind the scenes, ColdFusion created a Java map to store session state and added it to the Servlet session scope under the name cfsession. This Servlet retrieves the ColdFusion session state block with the expression: Map sessionVars = (Map)request.getSession().getAttribute(“cfsession”). Individual CFML session variables can thenceforth be accessed by their names. For example, the Servlet can get the value of the sessionvar ColdFusion session variable by using the expression sessionVars.get(“sessionvar”).
24.5. Accessing Enterprise Java Beans You want to access an Enterprise Java Bean from your ColdFusion template.
Technique Math.java: package org.acme.beans.math; import java.rmi.RemoteException; import javax.ejb.EJBObject; public interface Math extends EJBObject { public int add(int a, int b) throws RemoteException; public double add(double a, double b) throws RemoteException; public int factorial(int number) throws RemoteException; }
24.5.
Accessing Enterprise Java Beans
MathHome.java: package org.acme.beans.math; import java.rmi.RemoteException; import javax.ejb.CreateException; import javax.ejb.EJBHome; public interface MathHome extends EJBHome { public Math create() throws CreateException, RemoteException; }
MathBean.java: package org.acme.beans.math; import javax.ejb.CreateException; import javax.ejb.SessionBean; import javax.ejb.SessionContext; public class MathBean implements SessionBean { transient protected SessionContext ctx; public public public public public
public int add(int a, int b) { return a + b; } public double add(double a, double b) { return a + b; } public int factorial(int number) { int result = 1; for (int i = 2; i
