1 of 50

Base ORM Service

The BaseORMService is a core model CFC of the module that will provide you with a tremendous gammut of API methods to interact with ColdFusion ORM Entities.

Concept

The idea behind this support class is to provide a very good base or parent service layer that can interact with ColdFusion ORM via hibernate and entities inspired by Spring's Hibernate Template support. This means that you don't need to create a service layer CFC in order to work with ORM entities.

It provides tons of methods for query executions, paging, transactions, session metadata, caching and much more. You can either use the class on its own or create more concrete service layers by inheriting from this class.

Usage

In order to get started with the base ORM service you need to know how to get access to it. You can do this via WireBox injection DSL or by the model's ID.

WireBox DSL

The module also registers a new WireBox DSL called entityservice which can produce virtual or base orm entity services that you can use to inject into your own event handlers or models.

entityservice - Inject a global ORM service
entityservice:{entityName} - Inject a Virtual entity service according to entityName

Injection

You can also request a Base ORM Service via the registered WireBox ID which is exactly the same as the entityService DSL:

// Inject
inject name="ORMService" inject="BaseORMService@cborm";

// Retrieve
wireBox.getInstance( "BaseORMService@cborm" );
getModel( "BaseORMService@cborm" );

Implementation

Once you have access to the injected base ORM service, you can use it in all of its glory.

Important Please check out the latest API Docs for the latest methods and functionality.

component{

  inject name="ORMService" inject="entityService";

  function saveUser( event, rc, prc ){
      // retrieve and populate a new user object
      var user = populateModel( ORMService.new( "User" ) );

      // save the entity using hibernate transactions
      ORMService.save( user );

      setNextEvent( "user.list" );
  }

  function list( event, rc, prc ){

    //get a listing of all users with paging
    prc.users = ORMService.list(
        entityName= "User",
        sortOrder = "fname",
        offset     = event.getValue("startrow",1),
        max         = 20
    );

    event.setView( "user/list" );
  }
}

function index( event, rc, prc ){
    prc.data = ORMService.findAll( "Permission" );
}

Once you have a reference to the base ORM service then you can use any of its methods to interact with ORM entities. The drawback about leveraging the base ORM model is that you cannot add custom functions to it or tell it to work on a specific entity for all operations. It is a very simple API, but if you need more control then we can start using other approaches shown below.

Virtual Services

We also have a virtual service layer that can be mapped to specific entities and create entity driven service layers virtually. Meaning you don't have to be passing any entity names to the API methods to save you precious typing time.

Concrete Services

This is where you create your own CFC that inherits from our Base ORM Service model and either add or override methods. You can read more about it in our Concrete Services Section

Concrete Services

Let's say you are using the virtual services and base ORM service but you find that they do not complete your requirements, or you need some custom methods or change functionality. Then you will be building concrete services that inherit from the base or virtual entity services. This is the very purpose of these support classes as most of the time you will have custom requirements and your own style of coding. Here is a custom AuthorService we created:

/**
* Service to handle author operations.
*/
component extends="cborm.models.VirtualEntityService" accessors="true" singleton{

    // User hashing type
    property name="hashType";

    AuthorService function init(){
        // init it via virtual service layer
        super.init(entityName="bbAuthor", useQueryCaching=true);
        setHashType( "SHA-256" );

        return this;
    }

    function search(criteria){
        var params = {criteria="%#arguments.criteria#%"};
        var r = executeQuery(query="from bbAuthor where firstName like :criteria OR lastName like :criteria OR email like :criteria",params=params,asQuery=false);
        return r;
    }

    function saveAuthor(author,passwordChange=false){
        // hash password if new author
        if( !arguments.author.isLoaded() OR arguments.passwordChange ){
            arguments.author.setPassword( hash(arguments.author.getPassword(), getHashType()) );
        }
        // save the author
        save( author );
    }

    boolean function usernameFound(required username){
        var args = {"username" = arguments.username};
        return ( countWhere(argumentCollection=args) GT 0 );
    }

}

Then you can just inject your concrete service in your handlers, or other models like any other normal model object.

component{
    // Concrete ORM service layer
    property name="authorService" inject="security.AuthorService";
    // Aliased 
    property name="authorService" inject="id:AuthorService";

    function index( event, rc, prc ){
        // Get all authors or search
        if( len(event.getValue( "searchAuthor", "" )) ){
            prc.authors = authorService.search( rc.searchAuthor );
            prc.authorCount = arrayLen( prc.authors );
         } else {
            prc.authors        = authorService.list( sortOrder="lastName desc", asQuery=false );
            prc.authorCount     = authorService.count();
        }

        // View
        event.setView("authors/index");
    }
}

Service Properties

There are a few properties you can instantiate a base service with or set them afterwards that affect operation. Below you can see a nice chart for them:

So if I was to base off my services on top of this gem, I can do this:

component extends="cborm.models.BaseORMService"{

  public UserService function init(){
      super.init( useQueryCaching=true, eventHandling=false );
      return this;    
  }

}

Automatic Java Types

Most of the Hibernate extensions like criteria builders and even some dynamic finders and counters will have to rely on the underlying Java type in order to work. You do this in ColdFusion by using the javaCast() function available to you. So if you are using a primary key that is an Integer you might have to do the following in order to match your variable to the underlying Java type:

If you do not type it, then ColdFusion assumes it is a string and passes a string to Hibernate which will throw an exception as it is supposed to be an integer.

Auto Types

We have created two methods available to you in the base orm service, virtual service, criteria builders, active entity, etc to help you with these translations by automatically casting the values for you:

So instead of casting it manually you can just let us do the work:

Dynamic Finders- Counters

The ORM module supports the concept of dynamic finders and counters for ColdFusion ORM entities. A dynamic finder/counter looks like a real method but it is a virtual method that is intercepted by via onMissingMethod. This is a great way for you to do finders and counters using a programmatic and visual representation of what HQL to run.

This feature works on the Base ORM Service, Virtual Entity Services and also Active Entity services. The most semantic and clear representations occur in the Virtual Entity Service and Active Entity as you don't have to pass an entity name around.

Method Signatures

We have three types of dynamic finders and counters:

findBy : Find ONE entity according to method signature, if more than one record is found an exception is thrown
findAllBy : Find ALL entities according to method signature
countBy : Give you a count of entities according to method signature

Let's say you have the following entity:

component persistent="true" name="User" extends="cborm.models.ActiveEntity"{

     property name="id" column="user_id" fieldType="id" generator="uuid";
     property name="lastName";
     property name="userName";
     property name="password";
     property name="lastLogin" ormtype="date";
}

Then we could do the following:

user = entityNew( "User" ).findByLastName( "Majano" );

users = entityNew( "User" ).findAllByLastNameLike( "Ma%" );

users = entityNew( "User" ).findAllByLastLoginBetween( "01/01/2010", "01/01/2012" );

users = entityNew( "User" ).findAllByLastLoginBetweeninGreaterThan( "01/01/2010" );

users = entityNew( "User" ).findAllByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

count = entityNew( "User" ).countByLastLoginGreaterThan( "01/01/2010" );

count = entityNew( "User" ).countByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

You can also use the virtual entity service instead of active entity.

// Get a virtual entity service via DI, there are many ways to get a virtual entity service
// Look at virtual entity service docs for retrieval
property name="userService" inject="entityservice:userService";

user = userService.findByLastName( "Majano" );

users = userService.findAllByLastNameLike( "Ma%" );

users = userService.findAllByLastLoginBetween( "01/01/2010", "01/01/2012" );

users = userService.findAllByLastLoginGreaterThan( "01/01/2010" );

users = userService.findAllByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

count = userService.countByLastLoginGreaterThan( "01/01/2010" );

count = userService.countByLastLoginGreaterThanAndLastNameLike( "01/01/2010", "jo%" );

If you just use a vanilla Base ORM Service, then the first argument must be the entityName:

// Get a virtual entity service via DI, there are many ways to get a base entity service
// Look at base entity service docs for retrieval
property name="userService" inject="entityservice";

user = userService.findByLastName( "User", "Majano" );

Method Expressions

A method expression is made up of the prefixes: findBy, findAllBy, countBy followed by the expression that combines a query upon one or more properties:

User.findBy{property}[Conditional=equal][Operator]?{property}[Conditional][Operator]
User.findAllBy{property}[Conditional=equal][Operator]?{property}[Conditional][Operator]
User.countBy{property}[Conditional=equal][Operator]?{property}[Conditional][Operator]

If a conditional keyword is not passed, we assume you want equality. Remember that!

IMPORTANT The ? means that you can concatenate the same pattern over and over again.

Conditionals

The available conditionals in ColdBox are:

LessThanEquals - Less than or equal to passed value
LessThan - Less than to passed value
GreaterThanEquals - Greater than or equal to passed value
GreaterThan - Greater than to passed value
Like - Equivalent to the SQL like expression
NotEqual - Not equal to the passed value
isNull - The property must be null
isNotNull - The property must not be null
NotBetween - The property value must not be between two values
Between - The property value must be between two values
NotInList - The property value must not be in the passed in simple list or array
inList - The property value must be in the passed in simple list or array

Operators

The only valid operators are:

And
Or

Query Options

If you pass a structure as the last argument to your dynamic finder/counter call, we will consider that by convention to be your query options.

user = entityNew( "User" ).findByLastName( "Majano", { ignoreCase=true, timeout=20 } );

users = entityNew( "User" ).findAllByLastNameLike( "Ma%", { ignoreCase=false, max=20, offset=15 } );

The valid query options are:

ignorecase : Ignores the case of sort order when you set it to true. Use this option only when you specify the sortorder parameter.
maxResults : Specifies the maximum number of objects to be retrieved.
offset : Specifies the start index of the resultset from where it has to start the retrieval.
cacheable : Whether the result of this query is to be cached in the secondary cache. Default is false.
cachename : Name of the cache in secondary cache.
timeout : Specifies the timeout value (in seconds) for the query

clear

Clear the session removes all the entities that are loaded or created in the session. This clears the first level cache and removes the objects that are not yet saved to the database.

Returns

This function returns void

Examples

count

Return the count of instances in the DB for the given entity name. You can also pass an optional where statement that can filter the count. Ex: count('User','age > 40 AND name="joe"'). You can even use named or positional parameters with this method: Ex: count('User','age > ? AND name = ?',[40,"joe"])

Returns

This function returns numeric

Arguments

Examples

countWhere

Returns the count by passing name value pairs as arguments to this function. One mandatory argument is to pass the 'entityName'. The rest of the arguments are used in the where class using AND notation and parameterized. Ex: countWhere(entityName="User",age="20");

Returns

This function returns numeric

Arguments

createService

Create a virtual service for a specfic entity. Basically a new service layer that inherits from the BaseORMService object but no need to pass in entity names, they are bound to the entity name passed here.

Returns

This function returns VirtualEntityService

Arguments

Examples

criteriaCount

Update: Please use our updated objects instead so you can have much more control, granularity and coolness!

Get the record count using hibernate projections and criterion for specific queries

Returns

This function returns numeric

Arguments

Examples

criteriaQuery

Update: Please use our updated objects instead so you can have much more control, granularity and coolness!

Do a hibernate criteria based query with projections. You must pass an array of criterion objects by using the Hibernate Restrictions object that can be retrieved from this service using getRestrictions(). The Criteria interface allows to create and execute object-oriented queries. It is powerful alternative to the HQL but has own limitations. Criteria Query is used mostly in case of multi criteria search screens, where HQL is not very effective.

Returns

This function returns any which can be an array or query depending on passed arguments

Arguments

Examples

delete

Delete an entity using safe transactions. The entity argument can be a single entity or an array of entities. You can optionally flush the session also after committing.

Returns

This function returns void

Arguments

Examples

var post = ormService.get(1);
ormService.delete( post );

// Delete a flush immediately
ormService.delete( post, true );

deleteAll

Deletes all the entity records found in the database in a transaction safe matter and returns the number of records removed

Returns

This function returns numeric

Arguments

Examples

ormService.deleteAll("Tags");

deleteByID

Delete using an entity name and an incoming id, you can also flush the session if needed. The ID can be a single ID or an array of ID's to batch delete using hibernate DLM style deletes. The function also returns the number of records deleted.

Returns

This function returns numeric

Arguments

Examples

// just delete
count = ormService.deleteByID("User",1);

// delete and flush
count = ormService.deleteByID("User",4,true);

// Delete several records, or at least try
count = ormService.deleteByID("User",[1,2,3,4]);

deleteByQuery

Delete by using an HQL query and iterating via the results, it is not performing a delete query but it actually is a select query that should retrieve objects to remove

Returns

This function returns void

Arguments

| Key | Type | Required | Default | description | | query | string | Yes | --- | | | params | any | No | --- | | | max | numeric | No | 0 | | | offfset | numeric | No | 0 | | | flush | boolean | No | false | | | transactional | boolean | No | From Property | Use transactions or not | | datasource | string | false | | The datasource to use or use the default datasource |

Examples

// delete all blog posts
ormService.deleteByQuery("from Post");
// delete query with positional parameters
ormService.deleteByQuery("from Post as b where b.author=? and b.isActive = :active",['Luis Majano',false]);

// Use query options
var query = "from User as u where u.isActive=false order by u.creationDate desc"; 
// first 20 stale inactive users 
ormService.deleteByQuery(query=query,max=20); 
// 20 posts starting from my 15th entry
ormService.deleteByQuery(query=query,max=20,offset=15,flush=true);

// examples with named parameters
ormService.deleteByQuery("from Post as p where p.author=:author", {author='Luis Majano'})

deleteWhere

Deletes entities by using name value pairs as arguments to this function. One mandatory argument is to pass the 'entityName'. The rest of the arguments are used in the where class using AND notation and parameterized. Ex: deleteWhere(entityName="User",age="4",isActive=true);

Returns

This function returns numeric

Examples

ormService.deleteWhere(entityName="User", isActive=true, age=10);
ormService.deleteWhere(entityName="Account", id="40");
ormService.deleteWhere(entityName="Book", isReleased=true, author="Luis Majano");

evict

Evict an entity from session, the id can be a string or structure for the primary key You can also pass in a collection name to evict from the collection

Returns

This function returns void

Arguments

Examples

ormService.evict(entityName="Account",account.getID());
ormService.evict(entityName="Account");
ormService.evict(entityName="Account", collectionName="MyAccounts");

evictEntity

Evict entity objects from session. The argument can be one persistence entity or an array of entities

Returns

This function returns void

Arguments

Examples

// evict one entity
ORMService.evictEntity( entity );

// evict an array of entities
entities = [ user1, user2 ];
ORMService.evictEntity( entities );

evictQueries

Evict all queries in the default cache or the cache region that is passed in.

Returns

This function returns void

Arguments

Examples

// evict queries that are in the default hibernate cache
ormService.evictQueries();
// evict queries for this service
ormService.evictQueries( ormService.getQueryCacheRegion() );
// evict queries for my artists
ormService.evictQueries( "MyArtits" );

executeQuery

Allows the execution of HQL queries using several nice arguments and returns either an array of entities or a query as specified by the asQuery argument. The params filtering can be using named or positional.

Returns

This function returns any

Arguments

Examples

// simple query
ormService.executeQuery( "select distinct a.accountID from Account a" );
// using with list of parameters
ormService.executeQuery( "select distinct e.employeeID from Employee e where e.department = ? and e.created > ?", ['IS','01/01/2010'] );
// same query but with paging
ormService.executeQuery( "select distinct e.employeeID from Employee e where e.department = ? and e.created > ?", ['IS','01/01/2010'],1,30);

// same query but with named params and paging
ormService.executeQuery( "select distinct e.employeeID from Employee e where e.department = :dep and e.created > :created", {dep='Accounting',created='01/01/2010'],10,20);

// GET FUNKY!!

exists

Checks if the given entityName and id exists in the database

Returns

This function returns boolean

Arguments

Examples

if( ormService.exists("Account",123) ){
 // do something
}

findAll

Find all the entities for the specified query, named or positional arguments or by an example entity

Returns

This function returns array

Arguments

Examples

// find all blog posts
ormService.findAll("Post");
// with a positional parameters
ormService.findAll("from Post as p where p.author=?",['Luis Majano']);
// 10 posts from Luis Majano staring from 5th post ordered by release date
ormService.findAll("from Post as p where p.author=? order by p.releaseDate",['Luis majano'],offset=5,max=10);

// Using paging params
var query = "from Post as p where p.author='Luis Majano' order by p.releaseDate" 
// first 20 posts 
ormService.findAll(query=query,max=20) 
// 20 posts starting from my 15th entry
ormService.findAll(query=query,max=20,offset=15);

// examples with named parameters
ormService.findAll("from Post as p where p.author=:author", {author='Luis Majano'})
ormService.findAll("from Post as p where p.author=:author", {author='Luis Majano'}, max=20, offset=5);

// query by example
user = ormService.new(entityName="User",firstName="Luis");
ormService.findAll( example=user );

findAllWhere

Find all entities according to criteria structure. Ex: findAllWhere(entityName="Category", {category="Training"}), findAllWhere(entityName="Users", {age=40,retired=true});

Returns

This function returns array

Arguments

Examples

findByExample

Find all/single entities by example

Returns

This function returns array

Arguments

Examples

currentUser = ormService.findByExample( session.user, true );

findit

Finds and returns the first result for the given query or null if no entity was found. You can either use the query and params combination or send in an example entity to find.

Returns

This function returns any

Arguments

Examples

findWhere

Find one entity (or null if not found) according to a criteria structure ex: findWhere(entityName="Category", {category="Training"}), findWhere(entityName="Users",{age=40,retired=false});

Returns

This function returns any

Arguments

Examples

get

Get an entity using a primary key, if the id is not found this method returns null. You can also pass an id = 0 and the service will return to you a new entity.

Returns

This function returns any

Arguments

Examples

getAll

Retrieve all the instances from the passed in entity name using the id argument if specified. The id can be a list of IDs or an array of IDs or none to retrieve all. If the id is not found or returns null the array position will have an empty string in it in the specified order

Returns

This function returns array of entities found

Arguments

Examples

getEntityGivenName

Returns the entity name from a given entity object via session lookup or if new object via metadata lookup

Returns

This function returns string

Arguments

Examples

getKey

Returns the key (id field) of a given entity, either simple or composite keys. If the key is a simple pk then it will return a string, if it is a composite key then it returns an array

Returns

This function returns any

Arguments

Examples

// Assuming the following code has a dependency on a virtual entity service: property name="authorService" inject="entityService:Author"; var restrictions = authorService.getRestrictions(); var criteria = []; ArrayAppend(criteria, Restrictions.eq("firstName","Emily")); ArrayAppend(criteria, Restrictions.eq("firstName","Paul")); ArrayAppend(criteria, Restrictions.eq("firstName","Amy")); example1 = authorService.criteriaQuery([Restrictions.disjunction(criteria)]); var disjunction = ArrayNew(1); ArrayAppend(disjunction, Restrictions.eq("firstName","Emily")); ArrayAppend(disjunction, Restrictions.eq("firstName","Paul")); ArrayAppend(disjunction, Restrictions.eq("firstName","Amy")); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.gt("id",JavaCast("int",7))); ArrayAppend(criteria, Restrictions.disjunction(disjunction)); example2 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.eq("firstName","Michael")); prc.example1 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.ne("firstName","Michael")); prc.example2 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.in("firstName",["Ian","Emily","Paul"])); prc.example3a = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.in("id",JavaCast("java.lang.Integer[]",[2,5,9]))); prc.example3b = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.like("lastName","M%")); prc.example4 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.ilike("lastName","s%")); prc.example5 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.isEmpty("books")); prc.example6 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.isNotEmpty("books")); prc.example7 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.isNull("bio")); prc.example8 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.isNotNull("bio")); prc.example9 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.between("lastName","A","M")); prc.example10a = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.between("id",JavaCast("int",3),JavaCast("int",7))); prc.example10b = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.gt("id",JavaCast("int",8))); prc.example11 = authorService.criteriaQuery(criteria); var criteria = ArrayNew(1); ArrayAppend(criteria, Restrictions.ge("id",JavaCast("int",13))); prc.example12 = authorService.criteriaQuery(criteria);

populate

Populate an entity with a structure of name-value pairs. Make sure the names of the properties match the keys in the structure.

Returns

This function returns void

Arguments

INFO With composeRelationships=true, you can populate one-to-many, many-to-one, many-to-many, and one-to-one relationships from property values in the memento. For 'many-to-one' and 'one-to-one' relationships, the value of the property in the memento should be a single value of the primary key of the target entity to be loaded. For 'one-to-many' and 'many-to-many' relationships, the value of the property in the memento should a comma-delimited list or array of the primary keys of the target entities to be loaded.

Examples

var user = ormService.populate( ormService.new("User"), data );

// populate with includes only
var user = ormService.populate( ormService.new("User"), data, "fname,lname,email" );

//populate with excludes
var user = ormService.populate(target=ormService.new("User"),memento=data,exclude="id,setup,total" );

// populate with null values when value is empty string
var user = ormService.populate(target=ormService.new("User"),memento=data,nullEmptyInclude="lastName,dateOfBirth" );

// populate many-to-one relationship
var data = {
    firstName = "Luis",
    role = 1 // "role" is the name of the many-to-one relational property, and one is the key value
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the role relationship will be composed, and the value will be set to the appropriate instance of the Role model

// populate one-to-many relationship
var data = {
    firstName = "Luis",
    favColors = "1,2,3" ( or [1,2,3] ) // favColors is the name of the one-to-many relational property, and 1, 2 and 3 are key values of favColor models
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the favColors property will be set to an array of favColor entities

// only compose some relationships
var data = {
    firstName = "Luis",
    role = 1,
    favColors = [ 1, 3, 19 ]
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true, exclude="favColors" );
// in this example, "role" will be composed, but "favColors" will be excluded