BUG Community

Web people these days are spoiled with awesome frameworks and libraries. I personally love RoR and came to embrace jQuery library.

Most of you probably know that BUG comes with a web server and module data is served via web services. Very web friendly. They let you share data and create mash-ups quickly.

You have a number of options to create custom web services on BUG, and I hope to introduce you to these methods in this web dev series over the next few days.

PublicWSAdmin and PublicWSProvider2

The easiest way to create a web service is to use PublicWSAdmin and PublicWSProvider2. Note that I'm using the term "web service" very loosely. It could be highly standardized SOAP messages, XHTML page which is easier on the eyes, or simply a file.. anything you can reach via HTTP.

I'll use AccelerationGraph as an example here. This app exposes a service that displays a chart based on accelerometer readings. The chart gets updated every three seconds with a new reading so that you see a nifty animation. Quite fun to look at.

1. Using the New BUG Project wizard, create a BUG app and add "PublicWSAdmin" (com.buglabs.services.ws) as a required service.
2. In your project create a class that implements PublicWSProvider2. This is where you specify service public name (part of web service URL) and logics for HTTP methods such as GET and POST. In the example, AcceleratorGraphService contains implementation for web service. (Some code left out for readability) public class AcceleratorGraphService implements PublicWSProvider2 { private IAccelerometerSampleProvider accel; private String name = "AcceleratorGraph"; private FixedFiloQueue pastSamples; public AcceleratorGraphService(Object svc) { if (svc instanceof IAccelerometerSampleProvider) { this.accel = (IAccelerometerSampleProvider) svc; pastSamples = new FixedFiloQueue(30); } } public void setPublicName(String name) { this.name = name; } public PublicWSDefinition discover(int operation) { if (operation == PublicWSProvider2.GET) { return new PublicWSDefinition() { public List getParameters() { return null; } public String getReturnType() { return "text/html"; } }; } return null; } public IWSResponse execute(int operation, String input) { if (operation == PublicWSProvider2.GET) { return new IWSResponse() { public Object getContent() { return "my content goes here"; } public int getErrorCode() { return 0; } public String getErrorMessage() { return null; } public String getMimeType() { return "text/html"; } public boolean isError() { return false; } }; } else if (operation == PublicWSProvider2.POST) { return new IWSResponse() { public Object getContent() { return "my content goes here"; } public int getErrorCode() { return 0; } public String getErrorMessage() { return null; } public String getMimeType() { return "text/html"; } public boolean isError() { return false; } }; } return null; } public String getDescription() { return "Display accelerator graph"; } public String getPublicName() { return name; } }
3.  In your service tracker, create an instance for PublicWSAdmin and web service provider class you created in Step 2. Register your provider instance by passing it into PublicWSAdmin's registerService method. Since I need to output accelerometer reading, I'm passing in the accelerometer sample provider service to AcceleratorGraphService.  public void doStart() { accel = (IAccelerometerSampleProvider)getService(IAccelerometerSampleProvider.class); wsAdmin = (PublicWSAdmin)getService(PublicWSAdmin.class); ags = new AcceleratorGraphService(accel); wsAdmin.registerService(ags); } public void doStop() { if (wsAdmin != null) wsAdmin.unregisterService(ags); } 
4. If everything goes well, you should see your custom service listed in your service feed. On virtual BUG, you can check this by looking http://localhost:8082/service. <Services> <Service description="Returns a sample from the accelerometer" name="Acceleration"> <Get parameters="" returns="text/xml"/> </Service> <Service description="A web service message board." name="Statusbar"> <Get parameters="" returns="text/plain"/> <Put parameters="[Message]" returns="text/plain"/> </Service> <Service description="This service can return image data from a hardware camera." name="Picture"> <Get parameters="" returns="image/jpg"/> </Service> <Service description="Display accelerator graph" name="AcceleratorGraph"> <Get parameters="" returns="text/html"/> </Service> </Services>
5. Now to the fun stuff. In step 2, you've added implementations for PublicWSProvider2. The execute method is where you add HTTP response. Your return object is IWSResponse which contains actual content, mime type, and error info. In the example, I use both GET and POST. The GET action renders a HTML page with an image of chart and JavaScript necessary for ajax updates. The POST action is used to grab the latest g-force reading. A more proper way would be to use GET for both tasks and specify extensions so that .html returns the chart and .xml returns the latest reading. However, PublicWSProvider doesn't support extension yet. Here's source for GET (without Java code): <html> <script src="http://prototypejs.org/assets/2009/8/31/prototype.js" type="text/javascript"></script> <script type="text/javascript"> var data = []; // store g-force readings var repeater = null; function start_repeater() { repeater = setInterval('render_chart()', 3000); $('href_stop').show(); $('href_start').hide(); } function stop_repeater() { if (repeater) {clearInterval(repeater); $('href_stop').hide(); $('href_start').show(); } } Event.observe(window, 'load', function() {render_chart(); start_repeater();}); function render_chart() { var ajax = new Ajax.Request('/service/AcceleratorGraph', {method: 'post', onSuccess: function(resp) { var r = eval('('+resp.responseText+')'); data.push(r.value); $('span_value').innerHTML = r.value; $('img_chart').src = get_chart_url(); }}); } function get_chart_url() { var num_of_points = 20; var max_y = 2; var setting = { 'chart_type': 's', 'range': '', 'step': 10, 'dimension': '600x500', 'minmax': '' }; var start = (data.length <= num_of_points) ? 0 : (data.length-num_of_points); var end = data.length; setting.range = '0,' + start + ',' + (start+num_of_points) + ',1|1,0,' + max_y + ',.1'; setting.minmax = '0,' + num_of_points + ',0,' + max_y; var str_value_x = ''; var str_value_y = ''; var counter = 1; for (var i=start; i < end; i++) { str_value_x += counter + ','; str_value_y += data[i] + ','; counter++; } str_value_x = str_value_x.substring(0, str_value_x.length-1); str_value_y = str_value_y.substring(0, str_value_y.length-1); var url = 'http://chart.apis.google.com/chart?cht=' + setting.chart_type + '&chds=' + setting.minmax + '&chd=t:' + str_value_x + '|' + str_value_y + '&chxt=x,y&chxr=' + setting.range + '&chg=' + setting.step + '&chs=' + setting.dimension; return url; } </script><style>h2, span, a {font-family: Arial, Verdana; color:#555;} span { font-size: 14px;} img {width:600px; height: 500px; margin-bottom: 10px;}</style> <body> <h2>AcceleratorGraph</h2> <img id='img_chart' src='about:blank' /><br /> <span id='span_value'></span><br /><br /> <a id='href_stop' href='javascript:void(0);' onclick='stop_repeater();' >Stop</a> <a id='href_start' href='javascript:void(0);' onclick='start_repeater();'>Start</a> </body> </html> And POST is relatively easier: public Object getContent() { return "{value: " + getSample() + "}"; } If you need more examples of IWSResponse, look for IWSResponse.

Depending on complexity of your output, it may take rounds of trial and error (hopefully in virtual BUG) to get it right. If your content is more complicated and uses dynamic content excessively, you should consider using com.buglabs.osgi.sewing, which I'll cover in the next post.

In any case, setting up a custom web service on BUG is fairly easy, and makes sharing data as simple as hitting a URL in browser. Try it out and let me (amie [at] buglabs.net) know if you have any questions. Have fun! 

• webdev
• servlet
• http
• tutorial
• howto