Read a Record

Before you can read a Record you need to create a Record object. We'll be using the same ReactorFactory object we created for the gateway example:

<cfset reactor = CreateObject("Component", "reactor.reactorFactory").init(expandPath("reactor.xml")) />

Creating an instance of a record object is as simple as this:

<cfset UserRecord = reactor.createRecord("User") />

The syntax for this is essentially identical to creating a gateway and all other Reactor generated objects.

Let's take a moment and look at what we've got now. If you dump this object you'll see this result: (I've collapsed portions to make it smaller for this document).

By looking at the dump you can see that there 38 methods. Some of these we've discussed and most we haven't. These are all explained in the Record Object section.

There are, however, the 12 getter and setter methods, one for each field in the table. We also have the load(), save() and delete() methods. That leaves 23 other methods. Ignore them for now.

For fun, let's call the 6 getters methods using this code:

<cfoutput>
getUserId(): "#UserRecord.getUserId()#" 
getUsername(): "#UserRecord.getUsername()#" 
getPassword(): "#UserRecord.getPassword()#" 
getFirstName(): "#UserRecord.getFirstName()#" 
getLastName(): "#UserRecord.getLastName()#" 
getDateCreated(): "#UserRecord.getDateCreated()#" 
</cfoutput>

This results in the following output:

Not much of interest here. One thing I would like to point out is that getDateCreated() returned a date value. Depending on if your DBMS supports non-static default values, you may or may not see an empty string here. For at least MSSQL, a default expression which calls the getDate() method will be translated into now() in ColdFusion. I'll show a related trick for other DBMS in a bit.

Carrying on now…

Before we can load a record we need to tell the Record which row it represents. According to our schema, the User table has one primary key, userId. By default, Reactor relies on primary key values to identify specific rows to read (and all objects support multiple primary and foreign keys). You can also pass name/value pairs into the load() method to load arbitrary rows.

In my database I have one row. This row has a UserId value of 1. So, I'll set the userId value in my UserRecord to 1:

<cfset UserRecord.setUserId(1) />

Note: You wouldn't typically hard-code the value "1" into your application. This is just an example.

Now that the record "knows" its primary key you can load the data. Be warned! This might not be for the faint of heart:

<cfset UserRecord.load() />

Well, that wasn't that bad after all, was it? But what happened? Let's call those six methods again and see…

Isn't that cool?! Calling the load() method automatically populated the object with the correct data from the database!

This is a short-hand example of the same thing:

<cfset UserRecord = Reactor.createRecord("User").load(userId=1) />

So, what happens when you change the data and Save Changes to a Record?