org.jboss.remoting3
Interface Client<I,O>

Type Parameters:

I - the request type

O - the reply type

All Superinterfaces:

Attachable, Closeable, HandleableCloseable<Client<I,O>>

public interface Client<I,O>
extends HandleableCloseable<Client<I,O>>, Attachable

A communications client. The client may be associated with state maintained by the local and/or remote side.

This interface is part of the Remoting public API. It is intended to be consumed by Remoting applications; it is not intended to be implemented by them. Methods may be added to this interface in future minor releases without advance notice.

Nested Class Summary

Nested classes/interfaces inherited from interface org.jboss.remoting3.HandleableCloseable

HandleableCloseable.Key

Method Summary

O	invoke(I request) Send a request and block until a reply is received.
<T extends O> T	invoke(I request, Class<T> expectedResultType) Send a reqest and block until a reply is received, requiring the reply to be of a specific type.
<T extends O> T	invokeTyped(TypedRequest<? extends I,T> request) Send a typed request and block until a reply is received.
org.jboss.xnio.IoFuture<? extends O>	send(I request) Send a request asynchronously.
<T extends O> org.jboss.xnio.IoFuture<? extends T>	send(I request, Class<T> expectedResultType) Send a request asynchronously, requiring the reply to be of a specific result type.
<T extends O> org.jboss.xnio.IoFuture<? extends T>	sendTyped(TypedRequest<? extends I,T> request) Send a typed request asynchronously.

Methods inherited from interface org.jboss.remoting3.HandleableCloseable

addCloseHandler, awaitClosed, awaitClosedUninterruptibly, close

Methods inherited from interface org.jboss.remoting3.Attachable

getAttachments

Method Detail

invoke

O invoke(I request)
         throws IOException,
                CancellationException

Send a request and block until a reply is received. If the remote side manipulates a stream, the current thread may be used to handle it.

If the operation is cancelled asynchronously, a CancellationException is thrown. This exception indicates that the request was received and was executed, but a cancellation request was received and handled before the reply was able to be sent. The remote service will have cleanly cancelled the operation. This exception type is a RuntimeException; thus direct handling of this exception is optional (depending on your use case).

If the request is sent but the remote side sends an exception back, a RemoteExecutionException is thrown with the cause and message initialized by the remote service. This exception indicates an error in the execution of the service's RequestListener. The service will have cleanly recovered from such an exception.

If the request is sent and the remote side tries to reply, but sending the reply fails, a RemoteReplyException is thrown, possibly with the cause initialized to the reason of the failure. Typically this exception is thrown when serialization of the reply failed for some reason. This exception type extends RemoteExecutionException and can be treated similarly in most cases.

If the request is sent and the remote side sends the reply successfully but there is an error reading the reply locally, a ReplyException is thrown. In this case the operation is known to have completed without error but the actual detailed reply cannot be known. In cases where the reply would be ignored anyway, this exception type may be safely ignored (possibly logging it for informational purposes). This exception is typically caused by an ObjectStreamException thrown while unmarshalling the reply, though other causes are also possible.

If the result of the operation is known to be impossible to ascertain, then an IndeterminateOutcomeException is thrown. Possible causes of this condition include (but are not limited to) the connection to the remote side being unexpectedly broken, or the current thread being interrupted before the reply can be read. In the latter case, a best effort is automatically made to attempt to cancel the outstanding operation, though there is no guarantee.

If the request cannot be sent, some other IOException will be thrown with the reason, including (but not limited to) attempting to call this method on a closed client, or ObjectStreamExceptions related to marshalling the request locally or unmarshalling it remotely. Such an exception indicates that the remote side did not receive the request.

All these exceptions (apart from CancellationException) extend IOException which makes it easier to selectively catch only those exceptions that you need to implement special policy for, while relegating the rest to common handlers.

Parameters:

request - the request to send

Returns:

the result of the request

Throws:

CancellationException - if the operation was cancelled asynchronously

RemoteExecutionException - if the remote handler threw an exception

RemoteReplyException - if the remote side was unable to send the response

ReplyException - if the operation succeeded but the reply cannot be read for some reason

IndeterminateOutcomeException - if the result of the operation cannot be ascertained

ObjectStreamException - if marshalling or unmarshalling some part of the request failed

IOException - if some other I/O error occurred while sending the request

invoke

<T extends O> T invoke(I request,
                       Class<T> expectedResultType)
                   throws IOException,
                          CancellationException

Send a reqest and block until a reply is received, requiring the reply to be of a specific type. Otherwise this method functions identically to invoke(I).

Parameters:

request - the reqest to send

expectedResultType - the expected result type

Returns:

the result of the request

Throws:

IOException - if an I/O error occurred while sending the request

CancellationException - if the operation was cancelled asynchronously

See Also:

invoke(I)

invokeTyped

<T extends O> T invokeTyped(TypedRequest<? extends I,T> request)
                        throws IOException,
                               CancellationException,
                               ClassCastException

Send a typed request and block until a reply is received. If, for some reason, the given typed request object is not a subtype of <I>, a ClassCastException is thrown. Otherwise this method functions identically to invoke(I).

Type Parameters:

T - the specific reply subtype

Parameters:

request - the request

Returns:

the result of the request

Throws:

IOException - if an I/O error occurred while sending the request

CancellationException - if the operation was cancelled asynchronously

ClassCastException

send

org.jboss.xnio.IoFuture<? extends O> send(I request)
                                          throws IOException

Send a request asynchronously. If the remote side manipulates a stream, it may use a local policy to assign one or more thread(s) to handle the local end of that stream, or it may fail with an exception (e.g. if this method is called on a client with no threads to handle streaming).

This method may block until the request is sent; however once the request is sent, the rest of the request delivery and processing is fully asynchronous. The returned IoFuture object can be queried at a later time to determine the result of the operation. If the operation fails, one of the conditions described on the invoke(I) method will result. This condition can be determined by reading the status of the IoFuture object or by attempting to read the result.

Parameters:

request - the request to send

Returns:

a future representing the result of the request

Throws:

ObjectStreamException - if marshalling some part of the request failed

IOException - if some other I/O error occurred while sending the request

send

<T extends O> org.jboss.xnio.IoFuture<? extends T> send(I request,
                                                        Class<T> expectedResultType)
                                                    throws IOException

Send a request asynchronously, requiring the reply to be of a specific result type. Otherwise this method functions identically to send(I).

Type Parameters:

T - the expected result type

Parameters:

request - the request to send

expectedResultType - the expected result type class

Returns:

a future representing the result of the request

Throws:

ObjectStreamException - if marshalling some part of the request failed

IOException - if some other I/O error occurred while sending the request

See Also:

send(I)

sendTyped

<T extends O> org.jboss.xnio.IoFuture<? extends T> sendTyped(TypedRequest<? extends I,T> request)
                                                         throws IOException

Send a typed request asynchronously. If, for some reason, the given typed request object is not a subtype of <I>, a ClassCastException is thrown. Otherwise this method functions identically to send(I).

Type Parameters:

T - the expected result type

Parameters:

request - the request to send

Returns:

a future representing the result of the request

Throws:

ObjectStreamException - if marshalling some part of the request failed

IOException - if some other I/O error occurred while sending the request

See Also:

send(I)