org.osgi.service.async.delegate

Interface AsyncDelegate

@ConsumerType
public interface AsyncDelegate

This interface is used by services to allow them to optimize Asynchronous calls where they are capable of executing more efficiently.

This may mean that the service has access to its own thread pool, or that it can delegate work to a remote node, or act in some other way to reduce the load on the Asynchronous Services implementation when making an asynchronous call.

Method Summary

Modifier and Type	Method and Description
Promise<?>	async(Method m, Object[] args) Invoke the specified method as an asynchronous task with the specified arguments.
boolean	execute(Method m, Object[] args) Invoke the specified method as a "fire-and-forget" asynchronous task with the specified arguments.

Method Detail

async

Promise<?> async(Method m,
                 Object[] args)
          throws Exception

Invoke the specified method as an asynchronous task with the specified arguments.

This method can be used by clients, or the Async Service, to optimize Asynchronous execution of methods.

When called, this method should invoke the supplied method using the supplied arguments asynchronously, returning a Promise that can be used to access the result.

If the method cannot be executed asynchronously by this method then null must be returned.

Parameters:

m - The method to be asynchronously invoked.

args - The arguments to be used to invoke the method.

Returns:

A Promise representing the asynchronous result, or null if this method cannot be asynchronously invoked.

Throws:

Exception - An exception should be thrown only if there was a serious error that prevented the asynchronous task from starting. For example, the specified method does not exist on this object. Exceptions must not be thrown to indicate that the call does not support asynchronous invocation. Instead this method must return null. Exceptions must also not be thrown to indicate a failure from the execution of the underlying method. This must be handled by failing the returned Promise.

execute

boolean execute(Method m,
                Object[] args)
         throws Exception

Invoke the specified method as a "fire-and-forget" asynchronous task with the specified arguments.

This method can be used by clients, or the Async Service, to optimize Asynchronous execution of methods.

When called, this method should invoke the specified method using the specified arguments asynchronously. This method differs from async(Method, Object[]) in that it does not return a Promise. This method therefore allows the implementation to perform more aggressive optimizations because the end result of the invocation does not need to be returned to the caller.

If the method cannot be executed asynchronously by this method then false must be returned.

Parameters:

m - The method to be asynchronously invoked.

args - The arguments to be used to invoke the method.

Returns:

true if the asynchronous execution request has been accepted, or false if this method cannot be asynchronously invoked by the AsyncDelegate.

Throws:

Exception - An exception should be thrown only if there was a serious error that prevented the asynchronous task from starting. For example, the specified method does not exist on this object. Exceptions must not be thrown to indicate that the call does not support asynchronous invocation. Instead this method must return false. Exceptions must also not be thrown to indicate a failure from the execution of the underlying method.