5.11. Developing with the ServiceInvoker

This is the ServiceInvoker's code:

  public class ServiceInvoker
    {
        public ServiceInvoker(Service service) throws MessageDeliverException;
        public ServiceInvoker(String serviceCategory, String serviceName) throws MessageDeliverException;
			 public ServiceInvoker(Service service, List<PortReference.Extension> extensions);
        public Message deliverSync(Message message, long timeoutMillis) throws MessageDeliverException, RegistryException, FaultMessageException;
        public void deliverAsync(Message message) throws MessageDeliverException;
			public Service getService();
			public String getServiceCategory();
    }

Once you have created the instance, the client determines how to send messages to the service: synchronously (via deliverSync) or asynchronously (via deliverAsync). In the synchronous case, a timeout must be specified which represents how long the client will wait for a response. If no response is received within this period, a MessageDeliverException is thrown. The ResponseTimeoutException is derived from MessageDeliverException.

In a client-service environment the terms client and service are used to represent roles and a single entity can be a client and a service simultaneously. As such, you should not consider ServiceInvoker to be the domain of “pure” clients: it can be used within your Services and specifically within Actions. For example, rather than using the built-in Content Based Routing, an Action may wish to re-route an incoming Message to a different Service based on evaluation of certain business logic or an Action could decide to route specific types of fault Messages to the Dead Letter Queue for later administration.

The advantage of using ServiceInvoker in this way is that your Services will be able to benefit from the opaque fail-over mechanism described in the Advanced chapter. This means that one-way requests to other Services, faults etc. can be routed in a more robust manner without imposing more complexity on the developer.

One of the features of the ServiceInvoker is that of load balancing invocations in situations where there are multiple endpoints available for the target service. The ServiceInvoker supports a number of load balancing strategies as part of this feature.

When using the ServiceInvoker, preference is always given to invoking a service over its InVM transport if one is available. Other load balancing strategies are only be applied in the absence of an InVM endpoint for the target Service.