Transfer ORM is, as the name implies, an object relational mapper for Coldfusion. Transfer has a myriad of advanced features which can be intimidating for newcomers. Fortunately, Transfer can be installed and used very easily without learning some of the more advanced features. What follows are instructions you can use to install, configure and use transfer in a few simple steps.

Installation

UPDATE: Release Candidate 1.0 is now available.

The last official release of transfer is 0.6.3. This version is now quite old and it is recommended that you use the bleeding edge release (BER) from subversion. If you have any misgivings about using the BER, rest assured that many production systems are running the transfer BER. It's stable.

To install the transfer BER, point your subversion client to http://svn.riaforge.org/transfer and checkout or export the source from /trunk/transfer. You can either set a mapping for "/transfer" in the cf administrator, or drop the source transfer folder in your web root.

Configuration

To use transfer in an application you'll need to setup two configuration files. One for the datasource that transfer will use and another to describe the objects that transfer maps from your relational database. These files are typically named Datasource.xml and Transfer.xml, but you can use any name you like and/or append a .cfm extension to prevent the files from being visible in a web browser.

Datasource.xml

The transfer datasource.xml config specifies the values for the following:

- a datasource name that currently exists in the cf administrator - a username (if required - leave blank otherwise) - a password (if required - leave blank otherwise)

Transfer.xml

The transfer.xml file is used to define the properties and relationships of transfer objects that are mapped to the relational tables in your database. Objects can have onetomany, manytoone, or manytomany relationships. The following xml is the object definitions from the tBlog sample app.

Integration

Using Transfer with Coldspring

Using transfer as an application scope "singleton".

Usage

To grasp the full breadth of the transfer API, you really need to review the Transfer docs. I'll cover the four methods you will likely work with the most in the beginning. They are, get(), new(), save() and delete().

Using the tBlog object definitions above, to retrieve a post object use:

To have transfer return a new instance:

To modify and save a new post:

A small, but significant, benefit of using Transfer ORM, is that when you save an new object the object's state reflects it's new persisted state. So you can find out the new id by simply calling.

Lastly, transfer delete() method works like save(), you pass the transfer object to the method.

Much, much, more

This quick start is intended to help impatient types (like myself) get a taste for how simple it is to start using Transfer ORM. As you become comfortable with the Transfer API, you will definitely want to explore features like Transfer Object Decorators, the Transfer Event Model and Transfer Query Language (TQL). Mark Mandel has put a great deal of effort to into Transfer since it turned POSS. If you are not comfortable using the bleeding edge source code from subversion, keep an eye out for a 1.0 Release Candidate.

Yesterday, I asked Mark Mandel for some advice on tuning my object model for performance. Mark, being an ever-so-helpful (P)OSS author, gave me a few suggestions. Turns out that someone asked basically the same question on the transfer list today. Jaime Metcher made a couple of excellent points on choosing between queries and object composition. Paraphrasing, Jaime, when working with large data sets (the type of thing you might be tempted to use arrays of objects for), you will get better performance using a query. If you want to display a single instance of some object and the view is truly a composite, then your model should reflect that composition. Understanding this helps with choosing between onetomany or manytoone relationships for your object compositions.

[More]

I'm definitely marking this down in the "I should have known better" category. If you use MSSQL, you probably know by know that "user" is a reserved word. So, unless you use [user] as a table identifier it's imperative that you name your table something like "tbl_user" or use the plural "users". I don't like plural table names, so I opted for tbl_user. I just ran into a gotcha with my TQL for a query against tbl_user. Why? Here's a snippet from my method to check the uniqueness of a user e-mail.

// local vars struct
var local = StructNew();
// default result
local.result = false;
// tql for list
local.tql = "from user.User as user where user.Email = :Email AND user.Id != :Id";
//create a query object
local.query = getTransfer().createQuery(local.tql);
//set the named parameters
local.query.setParam("Email", getEmail(), "string");
local.query.setParam("Id", getId(), "numeric");
//run it
local.userList = getTransfer().listByQuery(local.query);
// if no records exist e-mail passes unique test
if (local.userList.recordcount eq 0)
{
	local.result = true;
}	
return local.result;

My transfer object class name is user.User, so why not alias that as "user"? That's a logical alias, right? Wrong!

After pulling my hair out debugging the ever-so-descriptive error message, [Macromedia][SQLServer JDBC Driver][SQLServer]Line 1: Incorrect syntax near '.'.

I finally decided to write up a unit test to try and get some meaningful debugging information. From there I pulled a query, ran that in the Query Analyzer. Scratched head a bit more, then...voila! Reserved word issue. How silly....

Of course, this is not purely a Transfer or even TQL problem, merely a cautionary tale regarding reserved words in MSSQL that I happened upon via Transfer TQL.

For the record, the new TQL query reads:

local.tql = "from user.User where user.User.Email = :Email AND user.User.Id != :Id";			

The other big a-ha moment for me is that if an error occurs within a method invocation, I should debug by unit testing, not re-initializing, rinsing and repeating on the client side.

If you use Transfer ORM you may have seen Mark Mandel's Advanced Transfer ORM Techniques presentation. One of the most interesting portions of this presentation (for me) was his coverage of the Transfer Event Model. Mark demonstrates how to setup a service (in this case a CryptService) as a Transfer Event listener. There are several events that objects can register to as listeners. One event type is "AfterNew", which is fired when a new transfer object is created. In the presentation Mark demonstrates how to leverage the Event Model with an AfterNew event and a decorated transfer object to encrypt/decrypt a user password. I wanted to use this concept for a new project, but rather than copying code verbatim from the presentation, I decided to try something a little different.

[More]

In this post I'll provide a deeper insight into how Dispatcher works and introduce the three generic views that make up the "generic admin". After generating some code with Illudium, we'll have all the pieces to perform CRUD operations...

[More]

I introduced a lot of pieces to the puzzle during parts 1 through 4 of this series and with this post, I hope to put them together. We'll look at a file and folder setup, ColdSpring and Transfer XML configuration files and the other files that form application for the generic admin...

[More]

If you are not using Illudium to generate your application classes, I encourage you to check it out. Out of the box, the code generator comes with several templates for generating CFCs, Transfer and ColdSpring XML, Actionscript VOs (value objects) and TOs (simple transfer objects designed for Flex development). Modifying, or creating your own templates is encouraged and easy. The template I developed for this series uses ColdFusion templating, but you can also use XSLT or a combination of both...

[More]