org.eclipse.ecf.remoteservice
Interface IRemoteService

All Known Implementing Classes:

AbstractClientService, AbstractRemoteService, RemoteServiceImpl, RestClientService

public interface IRemoteService

Interface providing runtime access to a remote service. An instance implementing this interface will be returned from the IRemoteServiceContainerAdapter.getRemoteService(IRemoteServiceReference) and may then be used to communicate with a remote service. The methods on this interface support accessing the remote service in several ways:

• callSync -- A synchronous invocation that will block the calling thread until complete (or timeout) and return the result from the remote or throw exception if remote invocation fails or throws exception
• callAsync/1 -- An asynchronous invocation that will not block the caller thread but rather return a non-null IFuture instance that can be polled for results. See IFuture.get(), IFuture.get(long), and IFuture.isDone(). timeout, exception, or successful completion)
• callAsync/2 -- An asynchronous invocation that will not block the caller thread but rather notify the given listener asynchronously when complete (via timeout, exception, or successful completion)
• fireAsync -- An asynchronous invocation that will simply execute the remote method asynchronously, but will not provide any response or remote method failure information
• getProxy -- Access to a local proxy for the remote service that will expose the appropriate interface to the caller, and synchronously call the remote methods when invoked. For example:

 IRemoteServiceReference[] references = serviceContainer
                .getRemoteServiceReferences(null, "java.lang.Runnable", null);
 IRemoteService remoteService = serviceContainer.getRemoteService(references[0]);
 Runnable runnable = (Runnable) remoteService.getProxy();
 runnable.run();
 

Method Summary

org.eclipse.equinox.concurrent.future.IFuture	callAsync(IRemoteCall call) Call remote method specified by call parameter asynchronously, and immediately return IFuture instance.
void	callAsync(IRemoteCall call, IRemoteCallListener listener) Call remote method specified by call parameter asynchronously, and notify specified listener when call starts and completes.
java.lang.Object	callSync(IRemoteCall call) Call remote method specified by call parameter synchronously.
void	fireAsync(IRemoteCall call) Fire remote method specified by call parameter.
java.lang.Object	getProxy() Get local proxy for remote interface.

Method Detail

callSync

java.lang.Object callSync(IRemoteCall call)
                          throws ECFException

Call remote method specified by call parameter synchronously.

Parameters:

call - the remote call to make

Returns:

Object the result of the call. Will be null if remote provides null as result.

Throws:

ECFException - thrown if disconnect occurs, caller not currently connected, or remote throws Exception

Since:

3.0

callAsync

void callAsync(IRemoteCall call,
               IRemoteCallListener listener)

Call remote method specified by call parameter asynchronously, and notify specified listener when call starts and completes.

Parameters:

call - the remote call to make. Must not be null .

listener - the listener to notify when call starts and is completed. The listener will be notified via the two event types IRemoteCallStartEvent and IRemoteCallCompleteEvent. Must not be null .

Since:

3.0

See Also:

IRemoteCallStartEvent, IRemoteCallCompleteEvent

callAsync

org.eclipse.equinox.concurrent.future.IFuture callAsync(IRemoteCall call)

Call remote method specified by call parameter asynchronously, and immediately return IFuture instance. Returned IFuture will not be null, and allows the caller to retrieve the actual resulting value from the remote call (or exception).

Parameters:

call - the remote call to make. Must not be null .

Returns:

IFuture the asynchronous result to allow the caller to poll for whether the result IFuture.isDone(), and then to IFuture.get() the actual result.

Since:

3.0

fireAsync

void fireAsync(IRemoteCall call)
               throws ECFException

Fire remote method specified by call parameter. The remote method will be invoked as a result of asynchronous message send, but no failure/exception information will be returned, and no result will be returned

Parameters:

call - the remote call to make. Must not be null .

Throws:

ECFException - if caller not currently connected

Since:

3.0

getProxy

java.lang.Object getProxy()
                          throws ECFException

Get local proxy for remote interface. The local proxy may then be used to make remote method calls transparently by invoking the local proxy method

Returns:

Object that implements the interface specified in the IRemoteServiceReference instance used to retrieve the IRemoteService object. The result may then be cast to the appropriate type. The getProxy() contract guarantees that if a non-null Object is returned, that it will implement the interface specified for the IRemoteServiceReference. Will not be null .

Throws:

ECFException - if not currently connected to remote service