Click here to close now.

Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Maureen O'Gara, Nancy Y. Nee, Tad Anderson, Daniel Kaar

Related Topics: ColdFusion

ColdFusion: Article

Creating and Accessing Collection Files

Creating and Accessing Collection Files

In computer terms, objects are abstracts of real-world entities that are all around us in everyday life. Examples of such objects could be people, organizations, cars, animals, or even less tangible entities such as math or time.

Of these examples, only the first four can be considered collections. One or more persons is a collection of people; one or more organizations is a collection of organizations, and so on. However, math is not a collection of math and time is not a collection of time. They are just simple objects with methods and properties. Simply defined, a collection is a set of related objects.

Several languages already use built-in objects that mimic real-world entities. Many of you may already be familiar with some form of Visual Basic or JavaScript. In Visual Basic, a group of related objects is called a collection. Although the term collection is foreign to the JavaScript language, the language does have objects that act like collections. For instance, the forms object is a collection. You can loop through the collection and access the individual objects using array syntax such as document.forms[0].

Collections come with many advantages. First, they are objects, so any and all advantages of objects, such as encapsulation and reusability, are inherent to the collection. Second, you can access a group of objects easily by looping through the collection and executing the same code against each object in the collection. Finally, you can simplify a lot of the external data manipulation by using collections. For instance, instead of returning a query containing users (which might change in six months) you could use a Users collection. The User object that is stored in the Users collection would encapsulate all the code that goes into retrieving the user data. That way, when the database changes, you can change your User object while your collection and the code accessing the collection remain the same.

What Makes a Collection?
There are three hard and fast rules that an object (or in ColdFusion, a component) has to adhere to in order to be a collection:
1.   Every object in the collection can be accessed individually. Each object in the collection is unique in instance, if not data. If there are five objects in the collection, you should be able to call properties and methods from each object.
2.   Every object in the collection is the same type of object and has the same properties and methods. This means that you wouldn't have a collection called People with two types of objects: People and Computers. You would, in fact, have two collections, the People collection and the Computers collection.
3.   A collection usually has at least four methods: Add, Remove, Count, and Item.

Most collections can be completely accessed through the use of just four methods:

  • Add(): Adds a new object to the collection
  • Remove(): Removes an object from the collection
  • Item(): Retrieves an object from the collection (for use in the application)
  • Count(): Returns the number of objects in the collection (for looping purposes)

    Creating the Collection Files
    In order to create a collection we need to create two files, both of which are CFCs. The first CFC we'll create will be named ActiveUsers.cfc; the second will be named ActiveUser.cfc. The ActiveUser.cfc file will be the actual object that is contained in our collection. The collection filename is usually the plural term for the name of our object, hence, ActiveUser object and ActiveUsers collection. The ActiveUser.cfc file is shown in Listing 1.

    The ActiveUsers collection will have four methods: Add(strFirstName, strLastName), Remove(index), Item(index), and Count(). Our ActiveUser object will contain five methods: GetName(), SetName(strFirstName, strLastName), SetLoginTime(), GetLoginTime(), and GetMinutesActive().

    Our ActiveUsers collection will be used to display only users who are currently active on our Web site, similar to a "who's on" interface. Anytime you access a variable in a shared scope, such as the Application scope, you should lock it using CFLOCK.

    The first step is to set up a data structure to store our data in the ActiveUsers collection. We need only one private (or member) variable called arItems, which is an array. You can add that code just inside of your CFCOMPONENT tag as shown below.

    <CFCOMPONENT>
    <CFSET arItems = ArrayNew(1)>
    </CFCOMPONENT>

    Next we're going to add four methods to the component. The first method is the Add method. The Add method will take two arguments, FirstName and LastName, both string literals. The Add function simply adds an element to the private variable arItems using the intrinsic function, ArrayAppend(). The tricky part is that our Add method needs to add a value that represents an instance of an object. Since we can't use the CFOBJECT tag inside the ArrayAppend() function, we will use the CreateObject() function, shown below. After we add that element to the array, we also need to get the length of the array so we know the index of our recently added user. Again, locking is important here, because we want to add an element to the array and then get the length of the array before anyone else adds another element to it. This is sometimes called a race or race to commit, in database terminology. If we don't lock the actions, we will be racing against other requests to add elements to the array, potentially returning the wrong values to the calling page.

    <CFSET ArrayAppend(arItems, CreateObject("component","ActiveUser")>
    <CFSET idx = ArrayLen(arItems)>

    The next two lines of code in our function will be calling methods from the prebuilt ActiveUser object. These methods set three internal variables in the ActiveUser object: the user's first name, the user's last name, and the date the user logged in.

    <CFSET arItems[idx].SetName(Arguments.FirstName,Arguments.LastName)>
    <CFSET arItems[idx].SetLoginTime(Now())>
    <CFRETURN arItem[idx]>

    The last thing we do is return the current element of the array for the programmer to use in the calling page, if necessary. That was the hard part. The next three functions are short and sweet, so I'm going to spend more time describing why you need to do this, rather than stepping through the code line by line. Listing 2 shows the code for the entire collection object.

    With the Remove method, we require one argument that is an integer representing the index of the internal array, arItems. We need to check to make sure the value passed is less than or equal to the length of the array so there aren't any errors produced, and then we simply remove that element using the ArrayDeleteAt() function. Remember, you'll need to lock this action to prevent the wrong index of the array from being deleted. In a situation where the method is called twice, there will be a race to commit the deletion. In the event the deletion was not locked, the array would be resized after the first deletion and then the wrong index could potentially be deleted during the second deletion.

    The Item method also requires an index value, but the result is different. Instead of removing an item (or doing any type of action), we're just going to return the instance of the ActiveUser object that was stored at that index. This allows us to access each individual object from external ColdFusion templates easily, as you'll see later.

    The Count method accepts no arguments and returns an integer describing the number of objects in our collection. We use the ArrayLen() function to determine the return value.

    That's it for our collection. All of the internal code is written for our ActiveUsers collection to work properly. It's relatively easy to generate code for collections once you understand the concepts. Now we're going to look at how to use collections in ColdFusion templates.

    Making the Collection Persist
    In order for our "who's on" application to persist, we need to set up the ActiveUsers collection in the Application scope. Open the Application.cfm file in Listing 3 and add the following code:

    <CFIF NOT IsDefined("Application.objActiveUsers")>
    <CFOBJECT NAME="Application.objActiveUsers" COMPONENT="ActiveUsers">
    </CFIF>

    This code basically says to check whether the Application.objActiveUsers collection is defined at the beginning of every request. If it isn't defined, it will create the collection using the CFOBJECT tag.

    Accessing the Collection
    In the index.cfm file (see Listing 4) we're going to output the current number of users online and then loop through the ActiveUsers collection and output data pertaining to the users that are online. You can do all this using the code below:

    <CFSET iCount = Application.objActiveUsers.Count()>

    As you'll see, we've set the iCount variable to the value of the ActiveUsers collection's Count method. This lets us know how many active users are online right now. Now we can loop through the collection using a simple FROM/TO (or FOR) loop where the TO attribute is equal to the number of users online, or iCount.

    We can access the individual objects in the collection using the Item(index) property such as Application.objActiveUsers.Item(i). In the code below, we use that notation to call different methods of the object, such as GetName(), GetLoginTime(), and GetMinutesActive().

    <CFLOOP FROM="1" TO="#iCount#" INDEX="i">
    <CFSET stName = Application.objActive
    Users.Item(i).GetName()>
    #i# - #stName["FirstName"]#
    #stName["LastName"]# -
    #DateFormat(Application.objActiveUsers.Item(i).GetLoginTime(), 'm/d/yy')#
    #TimeFormat(Application.objActiveUsers.Item(i).GetLoginTime(), 'h:mm tt')# -
    #Application.objActiveUsers.Item(i).GetMinutesActive()#<BR>
    </CFLOOP>

    Running index.cfm at this point in time would result in the printing of "Number of Users: 0", since we haven't added any users to the collection. In order to add users to the collection we have to call the Add() method of the ActiveUsers collection. In this example, we'll make a ColdFusion page called AddUser.cfm (see Listing 5) that requires two URL variables called FirstName and LastName. The following code is all we'll use for our AddUser.cfm file:

    <CFSET objActiveUser = Application.objActive
    Users.Add(Trim(URL.FirstName),Trim(URL.LastName))>
    <CFLOCATION URL="index.cfm">

    If we access the AddUser.cfm page passing "Steve" and "Parks" through the query string such as

    AddUser.cfm?FirstName=Steve&LastName=Parks

    our page will then add the user to the collection and refresh us to the index.cfm page. You should now see that there is one user named Steve Parks in the collection. If your browser caches the index.cfm page, you may have to manually refresh the page. In the index.cfm file we called the GetName(), GetLoginTime(), and GetMinutesActive() methods from the ActiveUser object in the collection. You'll now see that data outputted through the collection. Try it again, adding another user using your name. You should now see that you are in the collection as well.

    The last file that needs to be created is the RemoveUser.cfm file, which will remove users from the collection. Instead of passing the FirstName or LastName of the user, you'll need to pass a valid index. In this example, we'll just remove the first index, but in theory you would remove users based on an algorithm possibly determined by a method called GetMinutesIdle(). To remove the first user from the application, call the file RemoveUser.cfm, shown in Listing 6, passing a value of 1 in the attribute index, as shown below:

    RemoveUser.cfm?Index=1

    We've now created our ActiveUsers collection in a simplified form. You can add properties and methods to the ActiveUser object to make the system more robust. I recommend adding locking and validation to the Application scope and methods, respectively.

  • More Stories By Steve Parks

    Steve Parks, CEO of Adept Developer Consulting, Inc (www.adeptdeveloper.com), is a Macromedia Certified Advanced Cold Fusion Developer. Steve has seven years experience developing web applications and relational databases.

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


    @ThingsExpo Stories
    The 4th International Internet of @ThingsExpo, co-located with the 17th International Cloud Expo - to be held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA - announces that its Call for Papers is open. The Internet of Things (IoT) is the biggest idea since the creation of the Worldwide Web more than
    The 17th International Cloud Expo has announced that its Call for Papers is open. 17th International Cloud Expo, to be held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, brings together Cloud Computing, APM, APIs, Microservices, Security, Big Data, Internet of Things, DevOps and WebRTC to one location. With cloud computing driving a higher percentage of enterprise IT budgets every year, it becomes increasingly important to plant your flag in this fast-expanding business opportunity. Submit your speaking proposal today!
    Explosive growth in connected devices. Enormous amounts of data for collection and analysis. Critical use of data for split-second decision making and actionable information. All three are factors in making the Internet of Things a reality. Yet, any one factor would have an IT organization pondering its infrastructure strategy. How should your organization enhance its IT framework to enable an Internet of Things implementation? In his session at @ThingsExpo, James Kirkland, Red Hat's Chief Architect for the Internet of Things and Intelligent Systems, described how to revolutionize your archit...
    The 5th International DevOps Summit, co-located with 17th International Cloud Expo – being held November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA – announces that its Call for Papers is open. Born out of proven success in agile development, cloud computing, and process automation, DevOps is a macro trend you cannot afford to miss. From showcase success stories from early adopters and web-scale businesses, DevOps is expanding to organizations of all sizes, including the world's largest enterprises – and delivering real results. Among the proven benefits, DevOps is corr...
    SYS-CON Events announced today that Secure Infrastructure & Services will exhibit at SYS-CON's 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Secure Infrastructure & Services (SIAS) is a managed services provider of cloud computing solutions for the IBM Power Systems market. The company helps mid-market firms built on IBM hardware platforms to deploy new levels of reliable and cost-effective computing and high availability solutions, leveraging the cloud and the benefits of Infrastructure-as-a-Service (IaaS...
    To many people, IoT is a buzzword whose value is not understood. Many people think IoT is all about wearables and home automation. In his session at @ThingsExpo, Mike Kavis, Vice President & Principal Cloud Architect at Cloud Technology Partners, discussed some incredible game-changing use cases and how they are transforming industries like agriculture, manufacturing, health care, and smart cities. He will discuss cool technologies like smart dust, robotics, smart labels, and much more. Prepare to be blown away with a glimpse of the future.
    SYS-CON Events announced today that ProfitBricks, the provider of painless cloud infrastructure, will exhibit at SYS-CON's 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. ProfitBricks is the IaaS provider that offers a painless cloud experience for all IT users, with no learning curve. ProfitBricks boasts flexible cloud servers and networking, an integrated Data Center Designer tool for visual control over the cloud and the best price/performance value available. ProfitBricks was named one of the coolest Clo...
    17th Cloud Expo, taking place Nov 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA, will feature technical sessions from a rock star conference faculty and the leading industry players in the world. Cloud computing is now being embraced by a majority of enterprises of all sizes. Yesterday's debate about public vs. private has transformed into the reality of hybrid cloud: a recent survey shows that 74% of enterprises have a hybrid cloud strategy. Meanwhile, 94% of enterprises are using some form of XaaS – software, platform, and infrastructure as a service.
    Internet of Things is moving from being a hype to a reality. Experts estimate that internet connected cars will grow to 152 million, while over 100 million internet connected wireless light bulbs and lamps will be operational by 2020. These and many other intriguing statistics highlight the importance of Internet powered devices and how market penetration is going to multiply many times over in the next few years.
    The basic integration architecture, as defined by ESBs, hasn’t changed for more than a decade. Most cloud integration providers still rely on an ESB architecture and their proprietary connectors. As a result, enterprise integration projects suffer from constraints of availability and reliability of these connectors that are not re-usable across other integration vendors. However, the rapid adoption of APIs and almost ubiquitous availability of APIs amongst most SaaS and Cloud applications are rapidly redefining traditional integration approaches and their reliance on proprietary connectors. ...
    SYS-CON Events announced today that Dyn, the worldwide leader in Internet Performance, will exhibit at SYS-CON's 17th International Cloud Expo®, which will take place on November 3-5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Dyn is a cloud-based Internet Performance company. Dyn helps companies monitor, control, and optimize online infrastructure for an exceptional end-user experience. Through a world-class network and unrivaled, objective intelligence into Internet conditions, Dyn ensures traffic gets delivered faster, safer, and more reliably than ever.
    "We have a tagline - "Power in the API Economy." What that means is everything that is built in applications and connected applications is done through APIs," explained Roberto Medrano, Executive Vice President at Akana, in this SYS-CON.tv interview at 16th Cloud Expo, held June 9-11, 2015, at the Javits Center in New York City.
    WebRTC converts the entire network into a ubiquitous communications cloud thereby connecting anytime, anywhere through any point. In his session at WebRTC Summit,, Mark Castleman, EIR at Bell Labs and Head of Future X Labs, will discuss how the transformational nature of communications is achieved through the democratizing force of WebRTC. WebRTC is doing for voice what HTML did for web content.
    Today air travel is a minefield of delays, hassles and customer disappointment. Airlines struggle to revitalize the experience. GE and M2Mi will demonstrate practical examples of how IoT solutions are helping airlines bring back personalization, reduce trip time and improve reliability. In their session at @ThingsExpo, Shyam Varan Nath, Principal Architect with GE, and Dr. Sarah Cooper, M2Mi’s VP Business Development and Engineering, will explore the IoT cloud-based platform technologies driving this change including privacy controls, data transparency and integration of real time context wi...
    Buzzword alert: Microservices and IoT at a DevOps conference? What could possibly go wrong? In this Power Panel at DevOps Summit, moderated by Jason Bloomberg, the leading expert on architecting agility for the enterprise and president of Intellyx, panelists peeled away the buzz and discuss the important architectural principles behind implementing IoT solutions for the enterprise. As remote IoT devices and sensors become increasingly intelligent, they become part of our distributed cloud environment, and we must architect and code accordingly. At the very least, you'll have no problem fillin...
    The Internet of Things is not only adding billions of sensors and billions of terabytes to the Internet. It is also forcing a fundamental change in the way we envision Information Technology. For the first time, more data is being created by devices at the edge of the Internet rather than from centralized systems. What does this mean for today's IT professional? In this Power Panel at @ThingsExpo, moderated by Conference Chair Roger Strukhoff, panelists addressed this very serious issue of profound change in the industry.
    Internet of Things (IoT) will be a hybrid ecosystem of diverse devices and sensors collaborating with operational and enterprise systems to create the next big application. In their session at @ThingsExpo, Bramh Gupta, founder and CEO of robomq.io, and Fred Yatzeck, principal architect leading product development at robomq.io, discussed how choosing the right middleware and integration strategy from the get-go will enable IoT solution developers to adapt and grow with the industry, while at the same time reduce Time to Market (TTM) by using plug and play capabilities offered by a robust IoT ...
    It is one thing to build single industrial IoT applications, but what will it take to build the Smart Cities and truly society-changing applications of the future? The technology won’t be the problem, it will be the number of parties that need to work together and be aligned in their motivation to succeed. In his session at @ThingsExpo, Jason Mondanaro, Director, Product Management at Metanga, discussed how you can plan to cooperate, partner, and form lasting all-star teams to change the world and it starts with business models and monetization strategies.
    SYS-CON Events announced today that BMC will exhibit at SYS-CON's 16th International Cloud Expo®, which will take place on June 9-11, 2015, at the Javits Center in New York City, NY. BMC delivers software solutions that help IT transform digital enterprises for the ultimate competitive business advantage. BMC has worked with thousands of leading companies to create and deliver powerful IT management services. From mainframe to cloud to mobile, BMC pairs high-speed digital innovation with robust IT industrialization – allowing customers to provide amazing user experiences with optimized IT per...
    There will be 150 billion connected devices by 2020. New digital businesses have already disrupted value chains across every industry. APIs are at the center of the digital business. You need to understand what assets you have that can be exposed digitally, what their digital value chain is, and how to create an effective business model around that value chain to compete in this economy. No enterprise can be complacent and not engage in the digital economy. Learn how to be the disruptor and not the disruptee.