Guttershark Service Manager: HTTP Calls
A key thing in flash that has to be done all too often is making some sort of service call. If you’re not using an AS3 api for a social service, like (cough twitter), it tends to be annoying to implement - because you always write the same code to accomplish some http call, but it’s just sending different parameters.
Guttershark has a service manager that handles doing all this for you, with built-in options for retries, timeouts, maximum attempts, and a bunch of other stuff. And it’s all integrated with the Model, or you can use it by itself. Let’s take a look.
Manually setting up the service manager:
package { import net.guttershark.managers.ServiceManager; import net.guttershark.support.servicemanager.shared.CallResult; public class Main extends Sprite { private var sm:ServiceManager; public function Main() { sm = ServiceManager.gi(); sm.createHTTPService("searchGoogle","http://www.google.com/",3,5000); var data:Object = {}; data.q = "Guttershark"; sm.searchGoogle({ method:"get", data:data, responseFormat:"text", onResult:onGoogleResult, onFault:onGoogleFault, onRetry:onGoogleRetry, onTimeout:onGoogleTimedOut, onFirstCall:onGoogleFirstCall, }); } public function onGoogleResult(cr:CallResult):void { trace(cr.result); hideStatusIndicator(); } public function onGoogleFault(cf:CallFault):void { trace("FAULT"); hideStatusIndicator(); } public function onGoogleFirstCall():void { trace("first call to google service."); statusIndicator.show(); } public function onGoogleRetry():void { trace("retrying google service"); } public function onGoogleTimedOut():void { trace("timedout"); hideStatusIndicator(); } private function hideStatusIndicator():void { statusIndicator.hide(); } } }
Quick side note, please bare with me - some of this is a mix of psuedo code just to illustrate how the callbacks can be used to control different elements.
The above code is somewhat obvious, except for one line:
sm.createHTTPService("searchGoogle","http://www.google.com/",3,5000);
This creates a service called “searchGoogle”, who’s endpoint is that URL.. 3 is the number of attempts to allow, and 5000 is the timeout for each attempt. So in this case, it will call the service once, if a result or fault doesn’t happen within 5000 milliseconds, another attempt will be fired, so on and so fourth.
The service manager, like a couple other classes in Guttershark is a dynamic classes. So, when you create the http service, you can access it like a property of the service manager (sm.searchGoogle).
Easy though right? Let’s look at how it’s integrated with the model:
Model XML:
<?xml version="1.0" encoding="utf-8"> <model> <services> <service id="searchGoogle" url="http://www.google.com/" attempts="3" timeout="5000" /> <services> </model>
Here’s an update Main class file that extends doc controller to integrate the model:
package { import net.guttershark.control.DocumentController; import net.guttershark.managers.ServiceManager; import net.guttershark.support.servicemanager.shared.CallResult; public class Main extends DocumentController { override protected function flashvarsForStandalone():Object { return { model:"model.xml", initServices:true } } override protected function setupComplete():void { var data:Object = {}; data.q = "Guttershark"; sm.searchGoogle({ method:"get", data:data, responseFormat:"text", onResult:onGoogleResult, onFault:onGoogleFault, onRetry:onGoogleRetry, onTimeout:onGoogleTimedOut, onFirstCall:onGoogleFirstCall, }); } public function onGoogleResult(cr:CallResult):void { trace(cr.result); hideStatusIndicator(); } public function onGoogleFault(cf:CallFault):void { trace("FAULT"); hideStatusIndicator(); } public function onGoogleFirstCall():void { trace("first call to google service."); statusIndicator.show(); } public function onGoogleRetry():void { trace("retrying google service"); } public function onGoogleTimedOut():void { trace("timedout"); hideStatusIndicator(); } private function hideStatusIndicator():void { statusIndicator.hide(); } } }
Response Formats
The service manager, handles a few different types of response formats: text, binary, xml, and variables. The service manager will intelligently handle results, based off of those types.
For example, let’s say you make a service call to get some XML data. Let’s assume the request completed with a 200 OK. But, there was an error on the server side that caused a result to be returned that isn’t the expected data. As long as structure the XML a certain way, the service manager will call you onFault callback. Here’s an example:
XML Response Format
The service call:
sm.createHTTPService("myXMLService","http://example.com/xmlService",3,5000); sm.myXMLService({method:"post",responseFormat:"xml",...});
Successful result (will call the onResult callback):
<?xml version="1.0" encoding="utf-8"> <response> <someData>Hello World</someData> </response>
Trigger a fault:
<?xml version="1.0" encoding="utf-8"> <response> <fault>There was an error</fault> </response>
Variables Response Format
The service call:
sm.createHTTPService("myXMLService","http://example.com/xmlService",3,5000); sm.myXMLService({method:"post",responseFormat:"variables",...});
Successful result (will call the onResult callback):
&name=Aaron&lname=Smith&site=codeendeavor.com
Trigger a fault:
&fault=There was an error
You can access the result variables as an object on the CallResult, for example:
function onResult(cr:CallResult):void { trace(cr.result.lname); }
The only response formats that are intelligently handled are variables and xml. The other formats are raw data so you’d have to handle it yourself in the result callback.
Routes with Web Frameworks
The service manager can also handle routes for http services. The general ideas is that the “service” is the base URL to the site that exposes routes, then you tell the service manager which routes to append. For example:
sm.createHTTPService("myRestfulSite","http://www.example.com/",3,5000); var username:String = "b00g3r"; sm.myRestfulService({method:"GET", routes:["user",username,"friends"], responseFormat:"xml"});
This example will end up calling “http://www.example.com/user/b00g3r/friends”.
Conclusion
That’s all there is for HTTP services with the service manager. The service manager also exposes remoting, and SOAP - in the same dynamic/simplistic manner.
I would recommend reading the source that supports HTTP services:
net.guttershark.managers.ServiceManager; net.guttershark.support.servicemanager.shared.BaseCall net.guttershark.support.servicemanager.shared.CallResult net.guttershark.support.servicemanager.shared.CallFault net.guttershark.support.servicemanager.http.Service net.guttershark.support.servicemanager.http.ServiceCall
I’ll show you the remoting, and SOAP support next.
No comments yet. Be the first.
Leave a reply
RSS