org.cojen.dirmi.core

Interface StubSupport

public interface StubSupport

Object passed to a Stub instance in order for it to actually communicate with a remote object.

Author:

Brian S O'Neill

See Also:

StubFactory

Method Summary

Modifier and Type	Method and Description
void	batched(InvocationChannel channel) Called after batched request is sent over channel and current thread should hold channel.
void	batchedAndCancelTimeout(InvocationChannel channel) Called after batched request is sent over channel and current thread should hold channel.
<T extends Throwable,R extends Remote> R	createBatchedRemote(Class<T> remoteFailureException, InvocationChannel channel, Class<R> type) Used by batched methods which return a Remote object.
<V> Completion<V>	createCompletion(Object stub) Used by asynchronous methods which return a Future or Completion.
StubSupport	dispose() Returns a StubSupport instance which throws NoSuchObjectException for all of the above methods.
<T extends Throwable> T	failed(Class<T> remoteFailureException, InvocationChannel channel, Throwable cause) Called if invocation failed due to a problem with the channel, and it should be closed.
<T extends Throwable> T	failedAndCancelTimeout(Class<T> remoteFailureException, InvocationChannel channel, Throwable cause, double timeout, TimeUnit unit) Called if invocation failed due to a problem with the channel, and it should be closed.
<T extends Throwable> T	failedAndCancelTimeout(Class<T> remoteFailureException, InvocationChannel channel, Throwable cause, long timeout, TimeUnit unit) Called if invocation failed due to a problem with the channel, and it should be closed.
void	finished(InvocationChannel channel, boolean reset) Called after channel usage is finished and can be reused for sending new requests.
void	finishedAndCancelTimeout(InvocationChannel channel, boolean reset) Called after channel usage is finished and can be reused for sending new requests.
<T extends Throwable> InvocationChannel	invoke(Class<T> remoteFailureException) Writes request header to a free channel.
<T extends Throwable> InvocationChannel	invoke(Class<T> remoteFailureException, double timeout, TimeUnit unit) Writes request header to free channel.
<T extends Throwable> InvocationChannel	invoke(Class<T> remoteFailureException, long timeout, TimeUnit unit) Writes request header to a free channel.
void	rebatch(InvocationChannel channel) Called by unbatched methods to re-instate a thread-local channel.
void	release(InvocationChannel channel) Called if channel is to be used for returning a Pipe.
Pipe	requestReply(InvocationChannel channel) Called if channel is to be used for returning a request-reply Pipe.
Link	sessionLink() Returns a link to the session that stub is bound to.
boolean	stubEquals(StubSupport support) Returns a partial equals implementation for the Stub.
int	stubHashCode() Returns a hashCode implementation for the Stub.
String	stubToString() Returns a partial toString implementation for the Stub.
InvocationChannel	unbatch() Called by unbatched methods to temporarily release a thread-local channel.

Method Detail

sessionLink

Link sessionLink()

Returns a link to the session that stub is bound to.

unbatch

InvocationChannel unbatch()

Called by unbatched methods to temporarily release a thread-local channel.

Returns:

null if no batch is in progress

rebatch

void rebatch(InvocationChannel channel)

Called by unbatched methods to re-instate a thread-local channel.

Parameters:

channel - channel returned by unbatch; can be null

Throws:

IllegalStateException - if a thread-local channel already exists

invoke

<T extends Throwable> InvocationChannel invoke(Class<T> remoteFailureException)
                                        throws T extends Throwable

Writes request header to a free channel. Caller chooses to flush output after arguments are written and then reads channel.

Returns:

channel for writing arguments and reading response

Throws:

T extends Throwable

invoke

<T extends Throwable> InvocationChannel invoke(Class<T> remoteFailureException,
                                               long timeout,
                                               TimeUnit unit)
                                        throws T extends Throwable

Writes request header to a free channel. Caller chooses to flush output after arguments are written and then reads channel.

Returns:

channel for writing arguments and reading response

Throws:

T extends Throwable

invoke

<T extends Throwable> InvocationChannel invoke(Class<T> remoteFailureException,
                                               double timeout,
                                               TimeUnit unit)
                                        throws T extends Throwable

Writes request header to free channel. Caller chooses to flush output after arguments are written and then reads channel.

Returns:

channel for writing arguments and reading response

Throws:

T extends Throwable

createCompletion

<V> Completion<V> createCompletion(Object stub)

Used by asynchronous methods which return a Future or Completion.

Parameters:

stub - pass stub instance to prevent remote object from being identified as unreferenced

Returns:

completion which also implements RemoteCompletion

createBatchedRemote

<T extends Throwable,R extends Remote> R createBatchedRemote(Class<T> remoteFailureException,
                                                             InvocationChannel channel,
                                                             Class<R> type)
                                                      throws T extends Throwable

Used by batched methods which return a Remote object. This method writes an identifier to the channel, and returns a remote object of the requested type.

Parameters:

type - type of remote object returned by batched method

Returns:

stub for remote object

Throws:

T extends Throwable

batched

void batched(InvocationChannel channel)

Called after batched request is sent over channel and current thread should hold channel. This method should not throw any exception.

batchedAndCancelTimeout

void batchedAndCancelTimeout(InvocationChannel channel)

Called after batched request is sent over channel and current thread should hold channel. This method should not throw any exception.

release

void release(InvocationChannel channel)

Called if channel is to be used for returning a Pipe. This method should not throw any exception.

requestReply

Pipe requestReply(InvocationChannel channel)

Called if channel is to be used for returning a request-reply Pipe. This method should not throw any exception.

finished

void finished(InvocationChannel channel,
              boolean reset)

Called after channel usage is finished and can be reused for sending new requests. This method should not throw any exception.

Parameters:

reset - pass true if object output should be reset

finishedAndCancelTimeout

void finishedAndCancelTimeout(InvocationChannel channel,
                              boolean reset)

Called after channel usage is finished and can be reused for sending new requests. This method should not throw any exception.

Parameters:

reset - pass true if object output should be reset

failed

<T extends Throwable> T failed(Class<T> remoteFailureException,
                               InvocationChannel channel,
                               Throwable cause)

Called if invocation failed due to a problem with the channel, and it should be closed. This method should not throw any exception, however it must return an appropriate Throwable which will get thrown to the client.

failedAndCancelTimeout

<T extends Throwable> T failedAndCancelTimeout(Class<T> remoteFailureException,
                                               InvocationChannel channel,
                                               Throwable cause,
                                               long timeout,
                                               TimeUnit unit)

Called if invocation failed due to a problem with the channel, and it should be closed. This method should not throw any exception, however it must return an appropriate Throwable which will get thrown to the client.

failedAndCancelTimeout

<T extends Throwable> T failedAndCancelTimeout(Class<T> remoteFailureException,
                                               InvocationChannel channel,
                                               Throwable cause,
                                               double timeout,
                                               TimeUnit unit)

Called if invocation failed due to a problem with the channel, and it should be closed. This method should not throw any exception, however it must return an appropriate Throwable which will get thrown to the client.

dispose

StubSupport dispose()

Returns a StubSupport instance which throws NoSuchObjectException for all of the above methods.

stubHashCode

int stubHashCode()

Returns a hashCode implementation for the Stub.

stubEquals

boolean stubEquals(StubSupport support)

Returns a partial equals implementation for the Stub.

stubToString

String stubToString()

Returns a partial toString implementation for the Stub.