net.sf.mmm.service.api.client

Interface RemoteInvocationQueue

All Superinterfaces:

AttributeReadDefaultFailureCallback, AttributeReadId<String>, AttributeWriteDefaultFailureCallback

All Known Subinterfaces:

RemoteInvocationCommandQueue, RemoteInvocationServiceQueue

All Known Implementing Classes:

AbstractRemoteInvocationCaller.AbstractRemoteInvocationQueue, AbstractRemoteInvocationCommandCaller.RemoteInvocationCommandQueueImpl, AbstractRemoteInvocationServiceCaller.RemoteInvocationServiceQueueImpl

public interface RemoteInvocationQueue
extends AttributeReadId<String>, AttributeWriteDefaultFailureCallback

This is the abstract interface for a queue of method-calls to one or multiple RemoteInvocationServices. It acts like a transaction that can be committed or cancelled. While the queue is open , the user can add invocations for a RemoteInvocationService to the queue. This can be repeated and will collect the service invocations. In order to send these invocations to the server use the commit() method. This approach typically gains performance (especially reduces overall latency) if multiple service methods have to be called in a row.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
void	cancel() This method cancels this queue.
void	commit() This method completes this queue.
Consumer<Throwable>	getDefaultFailureCallback() This method gets the default callback to handle failures that occurred on service invocations.
String	getId() This method gets the ID used to identify this object.
RemoteInvocationQueueState	getState() This method gets the RemoteInvocationQueueState of this queue.

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

setDefaultFailureCallback

Method Detail

getDefaultFailureCallback

Consumer<Throwable> getDefaultFailureCallback()

This method gets the default callback to handle failures that occurred on service invocations. It will be used as fallback if no failure callback is specified explicitly. Queues will inherit the default failure callback from their parent. A toplevel queue inherits from the invocation caller.

Specified by:

getDefaultFailureCallback in interface AttributeReadDefaultFailureCallback

Returns:

the default failure callback or null if no default is configured.

getId

String getId()

This method gets the ID used to identify this object. An ID should be unique. It will be used for error messages, logging, etc. and will therefore help you debugging problems if you specify a reasonable ID.

Specified by:

getId in interface AttributeReadId<String>

Returns:

the object's ID.

See Also:

RemoteInvocationCaller.newQueue(String)

getState

RemoteInvocationQueueState getState()

This method gets the RemoteInvocationQueueState of this queue. The RemoteInvocationQueueState of a new queue is initially RemoteInvocationQueueState.OPEN. After commit() is called the status turns to RemoteInvocationQueueState.COMITTED. After cancel() is called it turns to RemoteInvocationQueueState.CANCELLED. As soon as the status is closed (NOT RemoteInvocationQueueState.OPEN), it can NOT be opened anymore and further adding of service invocations to the queue will fail.

Returns:

the RemoteInvocationQueueState of this queue.

commit

void commit()

This method completes this queue. After the call of this method the queue can NOT be used anymore.
If this is the root-queue all collected invocations will be send to the server immediately on commit(). Otherwise, if this is a sub-queue (a queue created while another queue was already open), the collected invocations will be appended to the parent queue.
NOTE:
Committing an empty queue is cheap and will have no effect but closing the queue. Therefore it is totally legal to open a queue in your generic infrastructure by default then perform some sort of initialization that may or may not cause service invocations on that queue and finally commit the queue.

cancel

void cancel()

This method cancels this queue. All collected invocations will be discarded including those from sub-queues. If this queue has a parent queue, the parent queue is NOT affected by this operation.
NOTE:
This operation should only be used in very specific situations.