III. Developing w/ ColdSpring

III.I Service Layers and ColdSpring

ColdSpring was designed to work exceptionally well with a piece of application architecture known as a "service-layer". What this means is that the functionality comprised within many of the application's components is separated into logical units and each is abstracted behind a clean interface (interface as in api). This is interface is often called a "service". In some applications you might have a few components that make up one logical unit of functionality… a DAO to fetch and store object instances in a database, maybe a gateway for aggregating multiple objects of that same type into recordsets. The idea of a service layer is that you group that functionality together so that other pieces of the application that depend on those components can speak to them through a clean, well documented api (the service). You'll do your best to define that api as early as possible, because the less it changes the easier your life will be. The abstraction a service layer provides also makes it a lot easier to manage your dependencies, which is where ColdSpring comes in. The diagram below shows the importance of the service layer (which could also be referred to as your "public API". Not only do "clients" such as web-application controller layers, ajax, and flex depend on the service layer's api, but also components within your model. This is why having the dependency resolution features of ColdSpring at your disposal make it easy to provide any component in your application's model with any service api.

Even though CFML provides many rich abstractions of complicated programming tasks as simple tags, it still may be a good idea to put them behind a service layer. Take CFMAIL, for example. Sure you could sprinkle email notifications throughout an application by using CFMAIL, but the day requirements change you'll be happier if you put it behind a service (we'll call it our "NotificationService"). So say that you've been given the chore of making sure that the application sends out SMS messages as well as emails to anyone who's listed as having SMS. Well, if you used CFMAIL everywhere, you'd now have to go through and add this functionality, which could end up being a lot of code (and a lot of duplication). Alternatively, if you have a NotificationService that is used everywhere CFMAIL was supposed to be, you could make your changes in one place and the rest of the application would never even know about it. The problem is that before your application depended on CFMAIL, which is simply "available" from anywhere within CFML code. Now we need to provide the same level of ubiquity with our NotificationService, and that's not as easy. However, with ColdSpring, bringing the NotificationService into a component is an easy two step process:

1. Provide a way for the NotificationService to be supplied to the component that needs it. This is done by either an argument to its init method that is named NotificationService and of the same CFC type as the NotificationService, or you provide a public setNotificationService method, with one argument, with the same name and type just like the constructor argument.
    

2. Describe the dependency in ColdSpring's bean definition or make sure autowire is set to "byName" or "byType". Without autowiring, the bean definitions would look like this:
    

3. 1. Define your NotificationService
      <bean id="NotificationService" class="myApp.model.NotificationService"/>
       

   2. Then define your component that needs the NotificationService, and pass in the reference via constructor-arg or property (property is shown)

<bean id="ComponentThatNeedsNotificationService" class="myApp.model.ComponentThatNeedsNotificationService">

<property name="NotificationService">

<ref bean="NotificationService"/>

</property>

</bean>

The setter method within "ComponentThatNeedsNotificationService" would look like this:

<cffunction name="setNotificationService" returntype="void" output="false"

hint="Dependency: Notifcation Service">

<cfargument name="NotificationSerivce" type="myApp.model.NotificationService"

required="true"/>

<cfset variables.notificationService = arguments.notificationService/>

</cffunction>

The <cfset variables.notificationService = arguments.notificationService/> line makes sure "ComponentThatNeedsNotificationService" will retain a reference to the notification service so that it can be used until overwritten or "ComponentThatNeedsNotificationService" is destroyed. Thus anywhere "ComponentThatNeedsNotificationService" needs to send a notification it simply says something like:

<cfset variables.notificationService.send(…) /> instead of using <CFMAIL/>, and you can be happy that all Notfications are passing through one concise component in your application.

III.II ColdSpring and MVC frameworks

ColdSpring was also developed to fit in well with existing MVC (Model View Controller) frameworks, such as Fusebox 4 and Mach-II. To use ColdSpring with one of these frameworks, it's important to understand the "big picture", as in where ColdSpring sits in relation to the rest of the application. The following diagram illustrates ColdSpring's relationship in a MVC web application:

Why does the Controller layer need to communicate with ColdSpring? In some cases, it may only be to retrieve objects (beans) from the ColdSpring bean factory. In others, the Controller may handle setting up and configuring the bean factory. Either way, it's important to note that once the controller obtains a reference to a bean, it does not communicate "thru" ColdSpring.

For those who use the Mach-II framework for a controller, ColdSpring ships with a Mach-II plugin (coldspring.machii.coldspringPlugin.cfc) that automates the creation of the bean factory. The following diagram details MachII and ColdSpring together:

ColdSpring bean factories can be used completely transparently in Mach ii applications via the coldspring.machii.ColdspringPlugin. The Mach ii plugin handles initialization and storage of the ColdSpring bean factory, as well as 'auto-matically' wiring up all of your Mach ii plugins, filters, and listeners with any ColdSpring managed components they may require. All that is necessary is really to define the plugin in the plugins section of your Mach ii config file, preferably as the first plugin, so it has access to all subsequent plugins for auto-wiring. The plugin also provides relatively fine grained control over its behavior through configuration parameters.

The following parameters are available:

III.III ColdSpring and Remoting

III.III.I Remote Facades

ColdSpring also provides a good foundation for exposing your application model to remote method calls. Currently, the primary way to do this is to write remote facades, which expose ColdSpring beans to remote calls by containing methods with access="remote".

There is a good example of a Remote Facade in the "FeedViewer" example application (located within the /examples/ directory within the ColdSpring distribution).

III.III.II Using AOP to create remote proxies

You can also use ColdSpring's AOP framework to automatically create Remote Facade(s) for your components. As of the 1.0 Release, this approach will only work on CFMX 7 and higher. We are working on support for MX6.1 as well.

To use this functionality, first gain some understanding of ColdSpring's AOP framework. The overall approach is this:

• Define your components normally as <bean/>'s

• Create a new <bean/> using the coldspring.aop.framework.RemoteFactoryBean class.

• In the RemoteFactoryBean's definition, we must define the following properties:

• target, the actual <bean/> we are creating a remote interface cfc for

• serviceName, the name of the resulting remote inteface cfc

• absolutePath, the filesystem location where the remote interface cfc should be placed or relativePath, a path relative from your webroot

• remoteMethodNames, a matching pattern for which methods in our target component we want to remote proxy.

A simple example definition would be:

<bean id="someComponent" class="type.of.SomeComponent"/>

<bean id="someComponent_Remote" class="coldspring.aop.framework.RemoteFactoryBean">

<property name="target">

<ref bean="someComponent" />

</property>

<property name="serviceName">

<value>RemoteCatalogService</value>

</property>

<property name="relativePath">

<value>/remote/</value>

</property>

<property name="remoteMethodNames">

<value>get*</value>

</property>

</bean>

In order for this to work, we have to tell our remote proxy to actually create itself, so you can do one of two things.

1) You can call getBean('someComponent_Remote')on the BeanFactory and ColdSpring will create the proxy for you (you would see a remoteCatalogService.cfc in the /remote/ directory on your server. So you would want to add this call during application startup.

2) You can use the coldspring.aop.framework.RemoteFactoryBean api to control when the remote proxy is created. First you must obtain the RemoteFactoryBean itself from ColdSpring, and this is done by preceding the bean name with a "&", meaning, getBean("&someComponent_Remote") would return your RemoteFactoryBean, which exposes the following api for you to use:

III.III.III Automatic CFC to ActionScript object conversion

ColdSpring also ships with a few utility classes which can be to automatically marshall and unmarshall between CFCs and ActionScript objects. These classes are the coldspring.remoting.flash.FlashUtilityService and coldspring.remoting.flash.FlashMappings. The FlashUtilityService uses the FlashMappings component to accomplish this task. You would configure them like so:

<bean id="flashMappings" class="coldspring.remoting.flash.FlashMappings">

<constructor-arg name="mappings">

<list>

<map>

<entry key="cfcType">

<value>some.type.of.Component</value>

</entry>

<entry key="asType">

<value>some.actionscript.Type</value

</entry>

</map>

</list>

    </constructor-arg>

</bean>

<bean id="flashUtilityService" class="coldspring.remoting.flash.FlashUtilityService">

<property name="flashMappings">

<ref bean="flashMappings"/>

</property>

</bean>

So, you simply provide the mappings as a list of maps (array of structs), each containing both a cfcType and a corresponding actionScript type. In this case any some.type.of.Component would be converted to the ActionScript some.actionscript.Type class.

<bean id="someComponent" class="type.of.SomeComponent"/>

<bean id="someComponent_Remote" class="coldspring.aop.framework.RemoteFactoryBean">

<property name="target">

<ref bean="someComponent" />

</property>

<property name="serviceName">

<value>RemoteCatalogService</value>

</property>

<property name="relativePath">

<value>/remote/</value>

</property>

<property name="remoteMethodNames">

<value>get*</value>

</property>

<property name="flashUtilityService">

<ref bean="flashUtilityService" />

</property>

</bean>