The ColdBox proxy enables remote applications or technologies like Flex, AIR, SOAP WebServices, Event Gateways, ColdFusion RESTful Webservices to communicate with ColdBox and provide an event driven model framework for those applications or for it to act as an enhanced service layer.

The one key feature here, is that ColdBox morphs into a remote event-driven framework and no longer an MVC framework that produces HTML.

The concept behind the ColdBox proxy is to create CFC's that extend our proxy class: coldbox.system.remote.ColdboxProxy. This will give you the ability to locate and talk to your running ColdBox application so you can proxy in requests from remote systems like Flex/Air, Event Gateways, ColdFusion REST/Soap Web Services and even CFC data binding.

component extends="coldbox.system.remote.ColdboxProxy"{

}

The concept of a Proxy is to give access to another system. As Wikipedia mentions:

"A proxy, in its most general form, is a class functioning as an interface to something else. The proxy could interface to anything: a network connection, a large object in memory, a file, or some other resource that is expensive or impossible to duplicate" Wikipedia

The proxy will give you access to your entire ColdBox application assets but also allow you to proxy in request to the normal ColdBox event model. You will do this via our process() method. This method expects an event argument to be passed to it which is the event string that will be executed for you and all the other arguments passed to this method will be converted and merged into the request collection according to their passed name.

Then your event handlers can respond to these requests just like normal requests and even return data back to the caller.

Hint The advanced ColdBox templates gives you a sample proxy object in your remote/MyProxy.cfc folder.

Organization

Most remote APIs are strongly typed so it makes sense to create as many ColdBox proxy objects as you see fit. Don't just create one proxy with 1000 methods on it. Try to apply identity to these objects as well. We also recommend you create a remote folder in your application where you can store all your remote proxy objects.

/Application
  /remote
    + MyProxy.cfc

Here is a sample proxy object that just proxies a remote call

component extends="coldbox.system.remote.ColdboxProxy"{

    /**
    * Get user data
    * @id The id of the user list to return
    */
    array function getData( required numeric id ){
        arguments.event = "users.getListData";

        var results = super.process( argumentCollection=arguments );

        return results ?: [];
    }
}

AppMapping

However, since some of these requests won't be done via HTTP but other protocols like Flex/Air binary protocols or event gateways, your ColdBox application must know where in your server the application is located in, so the Application.cfc methods fire. By default, when using HTTP calls, ColdBox can auto-locate your application with no issues at all, but with Flex/AIR or other protocols you must set this location in your Application.cfc via the COLDBOX_APP_MAPPING directive ONLY if not in the webroot of an application.

COLDBOX_APP_MAPPING   = "";

This tells the framework where in the web server (sub-folder) your application is located in. By default, your application is the root of your website so this value is empty or / and you won't modify this. But if your application is in a sub-folder then add the full instantation path here. So if your application is under /apps/myApp then the value would be:

COLDBOX_APP_MAPPING   = "apps.myApp";

Info The COLDBOX_APP_MAPPING value is an instantiation path value

The ColdBox Proxy also has the ability to use the request context's renderData() method. So you can build a system that just uses this functionality to transform data into multiple requests. Even have the ability for the same handler to respond to REST/SOAP and MVC all in one method:

Event Handler:

Proxy:

This handler can now respond to HTML requests, SOAP requests, Flex/Air Requests and even RESTFul requests. How about that!

The ColdBox.cfc has one setting that affects proxy operation:

• ProxyReturnCollection : This boolean setting determines if the proxy should return what the event handlers return or just return the request collection structure every time a process() method is called. This can be a very useful setting, if you don't even want to return any data from the handlers (via the process() method). The framework will just always return the request collection structure back to the proxy caller. By default, the framework has this setting turned to false so you can have more control and flexibility.

Now, what if you want to distinguish between a normal request and a proxy request? Well, the request context object, most commonly known as the event object has a method called:

• isProxyRequest : This boolean method determines what type of request is being executed.

The event handlers that you will produce for remote interaction are exactly the same as your other handlers, with the exception that they have a return type and return data back to the caller; our proxies. Then our proxies can strong type the return data elements:

Handler:

Hint The request context has a method called isProxyRequest() which tells the application if the request is coming from a ColdBox proxy.

Proxy:

The ColdBox Proxy also has a different life cycle than traditional MVC. All of a request's interception points fire with one addition: preProxyResults. This event fires right before the proxy returns results back to proxies. This is a great way to do transformations, logging, etc.

The most important gotchas in using the ColdBox proxy for remoting or even event gateways is pathing. Paths are totally different if you are using expandPath() or per-application mappings. Per-Application mappings can sometimes be a hassle for onSessionEnd(). So always be careful when setting up your paths and configurations for remoting. Try to always have the correct paths assigned and tested.

Here are some common methods of our ColdBox proxy object. However, we encourage you to see the API docs for that latest and greatest.

API Docs: http://apidocs.ortussolutions.com/coldbox/current