DataFaucet ORM

The Plumbing

This page describes the fundamental set of objects that drive the DataFaucet API. If you need or want to create new SQL Agents, add features, etc. these are the objects to see.

At the highest level, basic functional system objects are stored in the /datafaucet/system/ directory. Objects which are part of the SQL language abstraction (statement objects, and filters) are located in the /sql/ subdirectory and SQL Agenst which perform the task of translating query data into SQL code are stored in the /agent/ subdirectory.

the Faucet (bootstrap)

The entire DataFaucet system is loaded and managed by a relatively simple object in the system directory (bootstrap.cfc). This component's only purpose is to load the other system objects on an as-needed basis and if necessary to reinitialize them when they've been modified. Within your application the bootstrap object is referenced as request.DataFaucet and is the central portal through which all other objects become available.

DataManager

The DataManager is an object in the system directory (datamanager.cfc) responsible for getting active connections to SQL datasources and returning metadata with information about tables, columns and foreign key constraints in your database. Some of this information (column lists in particular) is cached in the datamanager for faster access. The DataManager also serves as the home of the default CacheManager although caching can also be performed at the database or the individual SQL select statement object.

Although the datamanger is stored in the server scope by default, you shouldn't reference it directly from that location except within a custom bootstrap.cfc. Bootstrap.cfc is the only object that should be allowed to reference the server scope directly to return the currently instantiated DataManager. All other objects then gain access to the DataManager through the bootstrap.

Sources

The source manager is another relatively simple object in the system directory (sources.cfc) which is stored in the application scope by default and its only purpose is to manage datasource objects for the current application and to be home to the SQL Agent locator. The agent locator is homed here to prevent potential conflicts with modified agents belonging to other applications on the same server.

Datasource

The faucet can manage multiple datasources per application via the Sources object although most of the time you'll only work with a single datasource in a given application. Each datasource object is responsible for holding information about the DSN (datasource, username, password), the type of SQL engine in use (MSSQL, MySQL, Oracle, MSAccess) and to be the single point of entry for building SQL Queries or gathering metadata about the database. Internally the datasource object uses the SQL library objects to build queries and the DataManager to collect its metadata however, to the "outside world", the datasource object IS the database for all intents and purposes. The datasource.cfc class file is located in the system directory.

SQL Agent Locator

The SQL Agent Locator object which is housed inside of the Sources object has only one purpose - to cache and return instances of the datasource engines stored in the system/agent directory. If a datasource object or a SQL statement object needs access to an Agent, it gets that agent from the locator.

SQL Agent

The SQL Agent is where the real magic of the DataFaucet system happens. Each platform-specific agent is a component in the system/agent directory which extends the system/agent/sqlagent.cfc component. By extending sqlagent.cfc each of these specific agents are able to override the default behavior of methods in the sqlagent.cfc, datadefinitionlanguage.cfc, engine.cfc and format.cfc which collectively hold all of the functionality for building and formatting queries. So in order to make DataFaucet work with an alternative database such as PostgreSQL or DB2, you would create your own CFC in the system/agent directory which extends sqlagent.cfc and where you would place any necessary methods to ensure that the generated SQL matches the requirements of that database platform.

CacheManager

The cache manager is yet again a relatively simple component object in the system directory (cachemanager.cfc) which stores the results of SQL Select statement execution for later use. By default there is one cache manager object which is stored in the DataManager although you can either replace the default cache manager or you can perform caching more granularly by setting a cache manager for the individual database or even an individual select statement object if desired. This allows you to create your own caching algorithms involving anything all the way up to external applications like memcached.

The default CacheManager object in the latest version of DataFaucet takes advantage of a new open source project called CacheBox, which provides consolidated caching from the application level all the way up to synchronizing a cluster, as well as hot-swapping of eviction policies and engines including memcached, ehCache, disk, etc. CacheBox also provides a convenient management application that makes it much easier to administer the cache across several applications on a server or cluster. Only a small portion of the CachBox project, the CacheBoxAgent (CFC) is included in DataFaucet, providing a very basic level of caching functionality. To get all the advanced features of CacheBox you'll need to download and install the CacheBox project separately. It should be as simple as extracting CacheBox to your webroot.