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

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

// 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.

Read more...

Once you get an appreciation for the importance of unit testing and integration testing is when we reach a new level in our development careers.  Testing is critical to mission critical applications, and even for our own little projects, where we test that our code should work as expected.  There’s that word again, expected.  Expectations in unit testing is like a nasty hamburger at a soccer match in El Salvador.  They go hand in hand :)

Read more...

Thanks to our 3.0.0 milestones, the SES capabilities have been really fine tuned and added some great concepts in order to enable it for more RESTful applications.  We have added things like:

• -alpha : Alpha only placeholders
• {X} : Digit quantifiers for all placeholders
• constraints : A separate structure where you can give any placeholder your own regular expression
• RESTful actions : A way to split actions according to the incoming HTTP method

The last one is what we will concentrate on.  In true RESTful style URLs, we must concentrate on the concept of resources or endpoints we are trying to describe.  Say: http://www.example.com/users  most likely will represent users, but we could also have: http://www.example.com/users/lmajano which describes a user but with a more detailed part which is lmajano.

Requests and responses are built around the transfer of "representations" of "resources"

"Representational State Transfer is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use."

It is also important to note that REST is a style of URL architecture not a mandate, so it is an open avenue of sorts.  However, you must stay true to its concepts of resources and usage of the HTTP verbs.  Here are a few pointers when using the HTTP verbs:

• POST : Create a resource
• GET : Retrieve a resource(s)
• PUT : Update a resource
• DELETE : delete a resource

So examples for true RESTful URLs:

• GET /users
  return a list of users
• GET /users/lmajano
  return the representation of user lmajano
• POST /users
  create a new user with post data
• PUT /users/lmajano
  Update the lmajano user
• DELETE /users/lmajano
  Delete the lmajano user

So how can we do this in ColdBox? Very easily! The new 3.0.0 SES interceptor allows for a pattern to be bounded to a handler and a structure of actions that match the incoming HTTP verbs:

// User representation

addRoute(pattern="users/:user",    
handler="rest.Users",    
action={    
GET = "show",    
POST = "create",    
DELETE = "remove",    
HEAD = "info"    
});

As you can see, the action argument can be a structure or a JSON structure of mappings between HTTP verbs and the action method you wish to fire whenever the resource is accessed with that method.  So if I go to /users/lmajano with a DELETE, then we will execute: rest.Users.remove().  So the approach of binding HTTP verbs to the correct actions, can give us TRUE RESTful URLs instead of us trying to create tons of URL representations and always using POST and GET. 

In conclusion, ColdBox 3.0.0 adheres to the standard RESTful principles and gives you a way to do HTTP verb to action mappings very easily when creating your resource URLs.  Stay tuned for more information on other useful RESTful features we have on 3.0 like:

• HTTP method security right from within your handlers
• onError() conventions when RESTful handlers throw exceptions
• Request context updates to retrieve headers and content
• Much more

Self admittedly, I am new to Unit Testing. It is on my list of things to learn and implement into my development toolbox and workflow for 2010. So, officially, I have begun the process using the Base Test Case ColdBox has built in and the illustrious MXUnit of course.

All my testing was working great until I wanted to test something that was using CF9 ORM/Hibernate integration.

The first issue I had was that ColdBox creates a separate application for testings. That is, the test folder has its own application.cfc defined. Well, obviously by default, that application.cfc doesn't have ORM setup, which then of course caused me not to be able to test anything that relied on or used an ORM "persistent=true" cfc or did an EntityLoad or anything like that.

So, the workaround for this issue is pretty simple.

First, open up the application.cfc in the test folder, then setup a mapping to your base application your testings. Call it whatever you like, I called my mapping baseApp.

this.mappings["/baseApp"] = expandpath('../../');

You can change the pathing to match your given scenario.

Then you need to configure orm in the application.cfc.

this.ormenabled = "true"; this.datasource = "MyDSN"; this.ormsettings = {cfclocation=["/baseApp/model/ORM","/baseApp/modules"]};

And there you have it, ORM is now configured for your testing application and you can test away.

Read more...

MockBox can have many amazing uses.  One well documented use is in assistance in creating complicated unit tests insuring you are only testing one small unit of work, it can be used for many other interesting use cases.

One of the ways we find MockBox useful during our development cycle at Computer Know How is to Mock objects we haven't had the time to complete yet, but we do know what we expect as response.  This allows us to continue development without waiting for the piece of something we haven't done yet slow us down, but keep the method calls exactly as they will be in when the object is complete.

So, how do you use MockBox outside of the context of a unit test?  Well, its easy.  

Inside a ColdBox application.

//get an instance of mockbox to use for mocking things not 100% built yet inside a ColdBox app mockBox = createObject("component","coldbox.system.testing.MockBox").init();

Outside a ColdBox application.

//get an instance of mockbox to use for mocking things not 100% built yet outside a ColdBox app. mockBox = createObject("component","mockbox.system.testing.MockBox").init();

Now that MockBox is initialized, we can start mocking objects. Lets say we have a User Object that we haven't had time to build yet. Right now it looks really advanced with lots of cool properties and functions that we spent a ton of time on. Something like this.

cfcomponent hint="I am the User ORM cfc" /cfcomponent

Read more...