I thought I would take a moment and explain some of the
different ways you can use the BaseORMService and VirtualEntityService extras
that are included in Coldbox 3.0 M5 and above.
Before I get into the different uses for each, lets define
them both and hopefully that will help clarify the differences
Base ORM Service:
The BaseORMService is an
amazing service layer tool that can be used in any project. The idea behind
this support class is to provide a very good base service layer that can
interact with hibernate and entities inspired by Spring's Hibernate Template support.
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. We also have
a virtual service layer that can be mapped to specific entities and create
entity driven service layers virtually. ColdBox also offers several
integrations to this class via plugins and the autowire DSL.
Virtual Entity
Service:
The virtual entity service is
another support class that can help you create virtual service layers that are
bounded to a specific entity for convenience. This class inherits from our Base ORM Service and
allows you to do everything the base class provides, except you do not need to
specific which entityName you
are working with. You can also use this class as a base class and template out its
methods to more concrete usages.
BaseORMService/ORMService Plugin
So first, how might you use the Base ORM Service extra
First, you could use it to create a concrete service that
has all the BaseORMService methods in it.
For example. UserService.cfc might look like this
import
coldbox.system.orm.hibernate.*
component
extends="BaseORMService"{
public UserService function init(){
super.init(useQueryCaching=true);
return this;
}
}
Then you can call things like this
function list(event){
var rc = event.getCollection();
var UserService = getModel("UserService");
//get a listing of all users with paging
rc.users = UserService.list(entityName="User",sortBy="fname",offset=event.getValue("startrow",1),max=20);
event.setView("user/list");
}
Or any of the other available methods in the
BaseORMSerivce. Now with our
UserService, we are free to add any of our own business logic to that service
that is needed, but have a ton of really cool methods already available to us.
Another way to use the BaseORMService, and I think a simpler
way if via the ORMService Plugin. This
plugin gives you access to all the methods in the BaseORMService.
Mainly, I don’t directly use the BaseORMService cfc. I either create services based of the
VirtualEntityService, via the AutowireDSL (which I will explain shortly), or
use these features via the ORMService Plugin.
To use the ORMService plugin, we can modify our code above
slightly and are ready to go.
function list(event){
var rc = event.getCollection();
//get a listing of all users with paging
rc.users = getPlugin("ORMService").list(entityName="User",sortBy="fname",offset=event.getValue("startrow",1),max=20);
event.setView("user/list");
}
I find myself using the ORMService Plugin extensively, so I
also always autowire it to my handler, making the code above even simpler.
// A handler
component{
property name="ORMService" inject="coldbox:plugin:ORMService";
function list(event){
var rc = event.getCollection();
//get a listing of all users with paging
rc.users = ORMService.list(entityName="User",sortBy="fname",offset=event.getValue("startrow",1),max=20);
event.setView("user/list");
}
}
How easy is that.
Tons of functionality right at your fingertips.
VirtualEntityService /Autowire Entity DSL
Generally when creating a concrete service I want to base
off of the BaseORMService, I extend the VirtualEntityService and initialize it
using the name of the entity that the service concerns.
Basically, the VirtualEntityService inherits from the BaseORMService
and allows you to template out its methods to a specific entity for more
concrete uses. This eliminates the need
to type entityName=”someEntity” in your calls, and anything that saves me
typing, saves me time and is a GOOD thing.
So, if I was creating that same UserService from above using
the VirtualEntityService, it would look like this.
import coldbox.system.orm.hibernate.*;
component extends="VirtualEntityService"{
public any function init(){
super.init( "User", true, "user.query.cache" );
return this;
}
// Override or add methods as you see fit now.
}
Pretty cool huh? Now my
list function looks like this
function list(event){
var rc = event.getCollection();
var UserService = getModel("UserService");
//get a listing of all users with paging
rc.users = UserService .list(sortBy="fname",offset=event.getValue("startrow",1),max=20);
event.setView("user/list");
}
So, removing the entityName=”User” from the call, but
if you had to call the service even 10 times, that’s a lot of typing saved.
Autowiring
There is also an autowiring DSL to quickly create services
based on a specific entity that you can use if don’t need any additional
methods or need to override any methods in your service layer.
Per the documentation
|
Type
|
Description
|
|
entityService
|
Inject a BaseORMService object
for usage as a generic service layer
|
|
entityService:{entity}
|
Inject a VirtualEntityService object
for usage as a service layer based off the name of the entity passed in.
|
// Generic ORM service layer
property name="genericService" inject="entityService";
// Virtual service layer based on the User entity
property name="userService" inject="entityService:User";
So, to implement our UserService and list function we have
had in our examples we could have a handler like this
// A handler
component{
property name="UserService" inject="entityService:User";
function list(event){
var rc = event.getCollection();
//get a listing of all users with paging
rc.users = UserService.list(sortBy="fname",offset=event.getValue("startrow",1),max=20);
event.setView("user/list");
}
}
For more information on the BaseORMService and
VirtualEntityService, here are some links to the complete documentation.
http://wiki.coldbox.org/wiki/Extras:BaseORMService.cfm
http://wiki.coldbox.org/wiki/Extras:VirtualEntityService.cfm
Hopefully this post helps you understand how you can use
these AWESOME extras in your environment.
Brad Wood |
Curt Gratz |
Scott Coldwell |
Luis Majano |
