200
edits
Changes
no edit summary
=WARNING: This is Outdated Documentation!!!!=
'''THIS IS OUTDATED DOCUMENTATION''' See new Umlaut documentation at http://github.com/team-umlaut/umlaut/wiki
---------
Part of [[Umlaut Technical Overview]]
===Statelessness===
(Not sure this is actually true any longer, working to make it not so. jrochkind jan 2010). Service logic should generally be written to be state-less. The same Service object, defined in services.yml, is initialized once and generally re-used for the life of an application instance (cached by ServiceList). So any state you store can end up persisting from request to request and session to session, which you probably don't intend. Umlaut architecture for background services also involves threads and forks, and while there's normally no reason a given service object would be in two threads simultaneously, better safe than sorry. It's safest to store no non-universal state in the service object.
===Disclosure methods===
===The handle method===
The heart of a typical service is in implementing the [http://umlaut.rubyforge.org/api/classes/Service.html#handle handle] method. When Umlaut wants a service to do it's thing, Umlaut will pass the request in, and it's up to the Service to do it's work. Note that while the individual umlaut request is passed into handle() as an argument for legacy purposes, it's also available from Service#request at any time, the argument isn't really necessary.
The service can examine all metadata from the request, and even examine ServiceResponses generated by other services, and the status of other services in progress or finished. (See [http://umlaut.rubyforge.org/api/classes/Request.html Request#dispatched_services], Request#dispatched, Request#services_in_progress, etc.)
The service can create one or more ServiceResponses. A ServiceResponse normally represents a discrete package of data that will be displayed on some part of the resolve menu. ServiceResponses should generally be created with the convenience method [http://umlaut.rubyforge.org/api/classes/Request.html Request]#add_service_response.
The add_service_response call has you specify the particular service class, the ServiceTypeValue, and arbitrary key value pairs as appropriate/conventional for the given time. For conventions on these key/value pairs, see [http://umlaut.rubyforge.org/api/classes/ServiceResponse.html ServiceResponse]. For example: <pre>request.add_service_response(:service=>self, :service_type_value => :cover_image, :display_text => 'Cover Image', :key=>size, :url => img.inner_html, :asin => asin, :size => size )</pre> The Service code is also responsible for registering a DispatchedService object with the completion state of the service. This should be done with the convenience method [http://umlaut.rubyforge.org/api/classes/Request.html Request]#dispatched . If the service throws an uncaught exception, Umlaut itself will register a DispatchedService with status FailedFatal. But otherwise, the service is responsible for registering a completion status, or Umlaut may not realize the service is complete and continue running it over and over again, or reporting it as timed out.
===callback methods===
The other service task we have defined currently as 'link_out_filter'. A task:link_out_filter service will never have it's handle method called. Instead, it will have a [http://umlaut.rubyforge.org/api/classes/Service.html Service#]link_out_filter method defined, and called at the appropriate control point. Examples of link_out_filter services are ezproxy, and sfx_backchannel_record.
[[Category: Umlaut]]
