====== Entourage Service Brokers ======

One of the key components of a rich web client application like those you will create with Entourage is client/server communication.  To help facilitate this communication, Entourage provides 'service brokers' that enable client/server RPC using a JSON data transport protocol.

{{:services:messaging_remote.png|}}

The Entourage Service Brokers utilize the message oriented architecture provided by [[mq:start|MQ]] to subscribe to and handle remote messages prefixed with ''r:'', which stands for "Remote".  Remote messages are dispatched to the server, and routed to the proper handler methods by a Service Broker, of which we have implementations for a number of programming languages and frameworks (see the list at left).


==== Service Brokers vs. REST Services ====

Should you use the Service Broker or RESTful Web Services?  It depends on the needs of your application.  If you'd like to have a public interface to your back end services (like a Flickr or Google, for example), RESTful services might be a better choice.  If your services primarily exist to service your web client application, then the Service Brokers will provide an easy to use RPC mechanism to invoke server-side logic.  In either case, your services //should// be mostly stateless and atomic, so that you can realize the full benefits of a client/server architecture.

==== Invoking remote services ====

There are two ways of invoking remote services:
  * Using the [[mq:sblistener|MQ JavaScript API]]
  * Using [[expressions:start|Entourage Expressions]]

Consult the documentation for those components for help on invoking and handling remote services from the client side.

==== Implementing remote services ====

For every Service Broker implementation, there is a means of annotating functions or methods to allow them to subscribe to remote messages sent by the client.  The syntax for these annotations varies based on the server-side programming language being used, but they generally follow a format like the following Java example:

<code java>
@Service(request="hello.request", response="hello.response")
protected void hello(Message request, Message response) {
  String yourMessage = request.getData().getString("your_message");
  response.getData().put("message", yourMessage);
}
</code>

Click on the server-side programming language/framework of your choice to learn more about using them to implement remote services.