Configure ORM



The configuration for ORM is done in Application.cfc which makes this configuration application specific. For a ColdFusion application to use ORM, the following are the mandatory settings that need to be configured:

  1. Enable ORM for the application. To do this, set the ormenabled property to true in the THIS scope of application.cfc

  2. Provide the data source name by either setting data source property to true in the THIS scope of application or by defining it in ORM configuration for the application.

    Note that the data source should be configured on the server.

The ORM configuration is specified using a struct called ormsettings, which is defined in the THIS scope of Application.cfc. The following table describes the settings for ORM that can be defined in Application.cfc.

Property Name

Description

ormenabled

Specifies whether ORM should be used for the ColdFusion application.Set the value to true to use ORM. The default is false.

datasource

Defines the data source that should be used by ORM.

ormsettings

The struct that defines all the ORM settings. For details, see ORM settings

    ORM settings

    The following settings can be set in the ormsettings struct that ColdFusion uses to configure ORM. All these settings are optional. If you specify the value of any ORM setting to true or yes, then the setting is enabled, otherwise it is disabled.

    Property Name

    Default

    Description

    autogenmap

    true

    Specifies whether ColdFusion should automatically generate mapping for the persistent CFCs. If autogenmap=false, mapping should be provided in the form of .HBMXML files.

    cacheconfig

    		  

    Specifies the location of the configuration file that should be used by the secondary cache provider.This setting is used only when secondarycacheenabled=true.

    See Secondary level cache for details.

    cacheprovider

    ehcache

    Specifies the cache provider that should be used by ORM as secondary cache. The values can be:

    • Ehcache

    • JBossCache

    • Hashtable

    • SwarmCache

    • OSCache

    Fully qualified name of the class for any other cache provider.

    This setting is used only when secondarycacheenabled=true.

    See Secondary level cache for details.

    catalog

    		  

    Specifies the default Catalog that should be used by ORM.

    cfclocation

    		  

    Specifies the directory (or array of directories) that should be used by ColdFusion to search for persistent CFCs to generate the mapping. If cfclocation is set, ColdFusion looks at only the paths specified in it. If it is not set, ColdFusion looks at the application directory, its sub-directories, and its mapped directories to search for persistent CFCs.

    datasource

    		  

    Specifies the data source that should be used by ORM. If it is not specified here, then the data source specified for the application is picked up.

    dbcreate

    none
    ColdFusion ORM can automatically create the tables for your application in the database at when ORM is initialized for the application. This can be enabled by using dbcreate in ormsettings. dbCreate takes the following values:

    • update: Setting this value creates the table if it does not exist or update the table if it exists.

    • dropcreate: Setting this value drops the table if it exists and then creates it.

    • none (default): Setting this value does not change anything in the database schema.

    dialect

    		  

    Specifies the dialect.

    ColdFusion supports the following dialects:

    • DB2

    • DB2AS400

    • DB2OS390

    • Derby

    • PostgreSQL

    • MySQL

    • MySQLwithInnoDB

    • MySQLwithMyISAM

    • Oracle8i

    • Oracle9i

    • Oracle10g

    • Sybase

    • SybaseAnywhere

    • MicrosoftSQLServer

    • Informix

    Apart from these dialects, you can specify custom dialects by using the fully qualified class name.

    Note: For Microsoft Access, dialect cannot be detected automatically. Use Microsoft SQL Server as the dialect for it.

    eventHandling

    false

    Specifies whether ORM Event callbacks should be given. See Event Handling in CFC for details.

    flushatrequestend

    true

    Specifies whether ormflush should be called automatically at request end. If flushatrequestend is false, ormflush is not called automatically at request end.

    See ORM session management.

    logSQL

    false

    Specifies whether the SQL queries that are executed by ORM will be logged. If LogSQL=true, the SQL queries are logged to the console.

    ormconfig

    		  

    The Hibernate configuration file.

    This file contains various configuration parameters like, dialect, cache settings, and mapping files that are required for the application. For more details, see www.hibernate.org/hib_docs/reference/en/html/session-configuration.html.

    The settings defined in the ormsettings override the settings defined in the Hibernate Configuration XML file.The connection information in the Hibernate Configuration XML file is however ignored because ColdFusion uses its own connection pool.

    You will need to use this only when you need to use a hibernate setting that is not available using ormsetting.

    savemapping

    false

    Specifies whether the generated Hibernate mapping file has to be saved to disk. If you set the value to true, the Hibernate mapping XML file is saved with the filename "CFC name".hbmxml in the same directory as the CFC.

    schema

    		  

    Specifies the default Schema that should be used by ORM.

    secondarycacheenabled

    false

    Specifies whether secondary caching should be enabled. See Use secondary cache for details.

    useDBForMapping

    true

    Specifies whether the database has to be inspected to identify the missing information required to generate the Hibernate mapping. The database is inspected to get the column data type, primary key and foreign key information.

    Sample Application.cfc 

    <cfset this.name = "ArtGallery"> 
    <cfset this.ormenabled = "true"> 
    <cfset this.ormsettings={datasource="cfartgallery", logsql="true"}>

    Logging

    Monitoring SQL queries that get generated and executed by ORM is critical for troubleshooting and performance optimization.

    You can monitor and log the queries by:

    • Defining logsql in ormsettings: This is a simple way to quickly enable SQL logging. The flag should be enabled in application.cfc:

      <cfset this.ormsettings.logsql = "true">

      This logs all the SQL queries that are generated by Hibernate to the console and server’s output log file.

    • Using log4J.properties: Hibernate uses log4j for its logging and you can completely control its logging including SQL by modifying the log4j.properties, which is present under <CF_HOME>/lib directory.

      Following is a sample snippet from the log4j.properties file:

      ###--------------- Hibernate Log Settings ------ 
### Set Hibernate log 
log4j.logger.org.hibernate=ERROR, HIBERNATECONSOLE 
 
### log just the SQL 
#log4j.logger.org.hibernate.SQL=DEBUG, HIBERNATECONSOLE 
#log4j.additivity.org.hibernate.SQL=false 
### Also log the parameter binding to the prepared statements. 
#log4j.logger.org.hibernate.type=DEBUG 
### log schema export/update ### 
log4j.logger.org.hibernate.tool.hbm2ddl=DEBUG, HIBERNATECONSOLE 
### log cache activity ### 
log4j.logger.org.hibernate.cache=ERROR, HIBERNATECONSOLE 
# HibernateConsole is set to be a ColsoleAppender for Hibernate message  using a PatternLayout. 
log4j.appender.HIBERNATECONSOLE=org.apache.log4j.ConsoleAppender 
log4j.appender.HIBERNATECONSOLE.layout=org.apache.log4j.PatternLayout 
log4j.appender.HIBERNATECONSOLE.layout.ConversionPattern=%d{MM/dd HH:mm:ss} [%t] HIBERNATE %-5p - %m%n%n 
#---------------------------------------------

      These settings control the SQLs that are generated for entity operations, how the data is bound to the statement while executing, what SQLs are generated for DDL, and what operations are performed on the secondary cache. All the logs get logged to console using HIBERNATECONSOLE which is actually a console appender. It can easily be changed to a FileAppender, which will then be logged to a log file. The configuration controls the logging for the following:

      • SQL generated for entity operations

      • Parameter binding for the prepared statements

      • SQL generated for DDL

      • Secondary cache operations

      With the default settings, all the logs get logged to console. You can also direct the logging to a log file using the FileAppender provided by log4j. See log4j for more details on Appenders.

      Log4j Properties

      Description

      log4j.logger.org.hibernate.SQL

      This controls when and how the SQL will be logged. DEBUG says all the SQL will be logged

      log4j.logger.org.hibernate.type

      This logs the parameter binding to the prepared statement.

      log4j.logger.org.hibernate.tool.hbm2ddl

      Logs SQL for DDL i.e schema export.

      log4j.logger.org.hibernate.cache

      Logs secondary cache information.