net.sf.mmm.service.api.rpc.client

Interface RemoteInvocationServiceCaller

All Superinterfaces:

AbstractRemoteInvocationServiceCaller, RemoteInvocationCaller<RemoteInvocationServiceQueue>

All Known Implementing Classes:

AbstractRemoteInvocationServiceCaller, AbstractRemoteInvocationServiceCallerGwt, AbstractRemoteInvocationServiceCallerWithClientMap, RemoteInvocationServiceCallerImplSpring

@ComponentSpecification
public interface RemoteInvocationServiceCaller
extends AbstractRemoteInvocationServiceCaller, RemoteInvocationCaller<RemoteInvocationServiceQueue>

This is the interface for the key component to invoke one or multiple RemoteInvocationServices from the client-side. The most simple usage is given in the following example:

 RemoteInvocationServiceCaller caller = getServiceCaller();
 MyService myService = caller.getServiceClient(MyService.class, MyResult.class, this::onSuccess, failure -> getLogger().error(failure));
 myService.myMethod(myArgument1, myArgument2);
 

However, there are advanced features such as queuing service calls and send them in a single technical request. Therefore you should use RemoteInvocationServiceQueue as illustrated by this example:

 RemoteInvocationServiceCaller caller = getServiceCaller();
 RemoteInvocationServiceQueue queue = caller.RemoteInvocationCaller.newQueue();
 queue.setDefaultFailureCallback(this::onFailure);
 MyService myService = queue.getServiceClient(MyService.class, MyResult.class, this::onSuccess, null);
 myService.myMethod(myArgument1, myArgument2);
 ...
 queue.commit();
 

This might look a little complex on the first view, but it allows very powerful but quite easy usage of asynchronous service invocations. In the example above a client-stub myService for the service-interface MyService is created. On this you can directly invoke the actual service method, here myMethod with the according arguments as you would do for a synchronous invocation. However, the method invocation will always return a dummy result (null for non-primitive return types) that you should ignore. Instead the method invocation including its arguments is recorded by the RemoteInvocationServiceQueue. It will be send to the server when the top-level queue is committed. When the result is received from the server, it will be passed to a callback function.
NOTE:
We have prepared everything for Java 1.8 so you can use lambdas. See net.sf.mmm.util.lang.api.function for details. If you are using a java version less than 1.8, you can NOT use lambdas and have to provide instances via anonymous classes.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
static String	CDI_NAME The CDI name.

Method Summary

Modifier and Type	Method and Description
<SERVICE extends RemoteInvocationService,RESULT> SERVICE	getServiceClient(Class<SERVICE> serviceInterface, Class<RESULT> returnType, Consumer<? extends RESULT> successCallback, Consumer<Throwable> failureCallback) This method gets a client-stub for calling exactly one single method on a RemoteInvocationService.

Methods inherited from interface net.sf.mmm.service.api.rpc.client.AbstractRemoteInvocationServiceCaller

getServiceClient

Methods inherited from interface net.sf.mmm.service.api.client.RemoteInvocationCaller

getCurrentQueue, newQueue, newQueue, newQueue

Field Detail

CDI_NAME

static final String CDI_NAME

The CDI name.

See Also:

Constant Field Values

Method Detail

getServiceClient

<SERVICE extends RemoteInvocationService,RESULT> SERVICE getServiceClient(Class<SERVICE> serviceInterface,
                                                                          Class<RESULT> returnType,
                                                                          Consumer<? extends RESULT> successCallback,
                                                                          Consumer<Throwable> failureCallback)

This method gets a client-stub for calling exactly one single method on a RemoteInvocationService. After this method has been called, the intended method (with the given returnType) has to be invoked on the resulting client-stub exactly once. This records the desired method invocation and returns a dummy result (typically null) that shall be ignored.
ATTENTION:
This is a convenience method for simplicity. It will create an implicit queue that gets committed automatically after a service method has been called on the returned client-stub.

Specified by:

getServiceClient in interface AbstractRemoteInvocationServiceCaller

Type Parameters:

SERVICE - is the generic type of serviceInterface.

RESULT - is the generic type of returnType.

Parameters:

serviceInterface - is the interface of the RemoteInvocationService.

returnType - is the return type of the Method to invoke.

successCallback - is the Consumer that is asynchronously invoked on success with when the result of the invoked service Method has been received. The generic type may extend result if it is generic itself. E.g. your service might return List<String> but you can only supply List.class as return type.

failureCallback - is the Consumer that is asynchronously invoked on failure with the Throwable that occurred when calling the invoked service Method.

Returns:

the client-stub of the RemoteInvocationService.