Skip navigation links

Oracle® Fusion Middleware Java API Reference for Oracle Coherence
12c (12.1.3.0.0)

E47890-01


com.tangosol.util.processor
Class AsynchronousProcessor

java.lang.Object
  extended by com.tangosol.util.AsynchronousAgent
      extended by com.tangosol.util.processor.AsynchronousProcessor

All Implemented Interfaces:
FlowControl, InvocableMap.EntryProcessor, java.io.Serializable, java.util.concurrent.Future

public class AsynchronousProcessor
extends AsynchronousAgent
implements InvocableMap.EntryProcessor

A marker EntryProcessor wrapper class that allows for an asynchronous invocation of the underlying processor. When used as a Future (without extending), this implementation will collect the results of asynchronous invocation into a Map, providing the result semantics identical to the EntryProcessor.processAll contract.

More advanced use would require extending this class and overriding onResult(java.util.Map.Entry), onComplete(), and onException(java.lang.Throwable) methods. It's very important that overriding implementations of these methods must be non-blocking. For example, any use of NamedCache API is completely disallowed with the only exception of AsynchronousAggregators and AsynchronousProcessors with disabled flow control.

The underlying entry processor is guaranteed to have been fully executed when onComplete() is called.

Note 1: Neither this class nor its extensions need to be serializable. Only the underlying processor is serialized and sent to corresponding servers for execution.
Note 2: This feature is not available on Coherence*Extend clients.

Author:
gg/mf 2012.12.21
See Also:
AsynchronousAggregator

Field Summary
protected  java.util.List m_listResultEntries
          List of result value entries.
protected  InvocableMap.EntryProcessor m_processor
          The underlying entry processor.

 

Fields inherited from class com.tangosol.util.AsynchronousAgent
m_control, m_eReason, m_fFlowControl, m_iOrderId, m_oResult

 

Constructor Summary
AsynchronousProcessor(InvocableMap.EntryProcessor processor)
          Construct an AsynchronousProcessor for a given processor and the automatic flow control "on"
AsynchronousProcessor(InvocableMap.EntryProcessor processor, boolean fFlowControl)
          Construct an AsynchronousProcessor for a given processor.
AsynchronousProcessor(InvocableMap.EntryProcessor processor, boolean fFlowControl, int iUnitOrderId)
          Construct an AsynchronousProcessor for a given processor.

 

Method Summary
 InvocableMap.EntryProcessor getProcessor()
          Obtain the underlying entry processor.
 int getUnitOfOrderId()
          Return a unit-of-order id associated with this processor.
 void onComplete()
          Called after the processor has been notified about all possible partial results or failures and no more are forthcoming.
 void onException(java.lang.Throwable eReason)
          Called if any part of the operation failed for any reason.
 void onResult(java.util.Map.Entry entry)
          Called when there is a partial result of the asynchronous execution.
 java.lang.Object process(InvocableMap.Entry entry)
          Not supported.
 java.util.Map processAll(java.util.Set setEntries)
          Not supported.

 

Methods inherited from class com.tangosol.util.AsynchronousAgent
bind, cancel, checkBacklog, drainBacklog, flush, get, get, isAutoFlowControl, isCancelled, isDone, setException, setResult, toString

 

Field Detail

m_processor

protected final InvocableMap.EntryProcessor m_processor
The underlying entry processor.

m_listResultEntries

protected java.util.List m_listResultEntries
List of result value entries. The reason we keep the result entries as a List rather than a Set or a Map is to skip unnecessary "equals" checks and defer potentially unneeded deserialization.

Constructor Detail

AsynchronousProcessor

public AsynchronousProcessor(InvocableMap.EntryProcessor processor)
Construct an AsynchronousProcessor for a given processor and the automatic flow control "on"
Parameters:
processor - the underlying InvocableMap.EntryProcessor

AsynchronousProcessor

public AsynchronousProcessor(InvocableMap.EntryProcessor processor,
                             boolean fFlowControl)
Construct an AsynchronousProcessor for a given processor.
Parameters:
processor - the underlying InvocableMap.EntryProcessor
fFlowControl - if true, the calling thread could be held by the service flow control logic (based on the destination backlog); otherwise it's the caller's responsibility to modulate the request flow (e.g. ensure that the invocation rate does not outpace the response rate)

AsynchronousProcessor

public AsynchronousProcessor(InvocableMap.EntryProcessor processor,
                             boolean fFlowControl,
                             int iUnitOrderId)
Construct an AsynchronousProcessor for a given processor.
Parameters:
processor - the underlying InvocableMap.EntryProcessor
fFlowControl - if true, the calling thread could be held by the service flow control logic (based on the destination backlog); otherwise it's the caller's responsibility to modulate the request flow (e.g. ensure that the invocation rate does not outpace the response rate)
iUnitOrderId - the unit-of-order id for this processor

Method Detail

onResult

public void onResult(java.util.Map.Entry entry)
Called when there is a partial result of the asynchronous execution.

For a given request, calls to this method and onException(java.lang.Throwable) may come concurrently.
For ordering guarantees across different processor invocations see getUnitOfOrderId().

Note: Overriding implementations of this method must be non-blocking.

Parameters:
entry - an entry holding the key and a result of the operation for the given key

onComplete

public void onComplete()
Called after the processor has been notified about all possible partial results or failures and no more are forthcoming. As long as this processor was submitted to any of InvocableMap's methods, this method is guaranteed to be called once and only once.

Possible call back sequences are:

  cache.invoke
    ...
    onResult
    onComplete

  cache.invoke
    ...
    onException
    onComplete

  cache.invokeAll
    ...
     onResult
     onException
     onException
     onResult
     onComplete
 
For ordering guarantees across processors see getUnitOfOrderId().

Note: Overriding implementations of this method must be non-blocking.


onException

public void onException(java.lang.Throwable eReason)
Called if any part of the operation failed for any reason. For operations that span multiple partitions this method could be called more than once. However, unless subclasses override this method, any failure will "complete" the operation.

Note: Overriding implementations of this method must be non-blocking.

Parameters:
eReason - the reason of failure

getUnitOfOrderId

public int getUnitOfOrderId()
Return a unit-of-order id associated with this processor. By default, the unit-of-order id is assigned to the calling thread's hashCode.

If two consecutive "invoke" calls are made using AsynchronousProcessors with the same order id and the same key set, then the corresponding execution and calls to onResult(java.util.Map.Entry) are going to happen in the exact same order.

If two consecutive "invoke" calls are made using AsynchronousProcessors with the same order id and the same partition set, then the the corresponding execution and calls to onComplete() are going to happen in the exact same order.

Note 1: The ordering guarantee is respected between AsynchronousProcessors and AsynchronousAggregators with the same unit-of-order id.
Note 2: There is no ordering guarantees between asynchronous and synchronous operations.

Returns:
the unit-of-order id associated with this processor

getProcessor

public InvocableMap.EntryProcessor getProcessor()
Obtain the underlying entry processor.
Returns:
the underlying entry processor

process

public java.lang.Object process(InvocableMap.Entry entry)
Not supported.
Specified by:
process in interface InvocableMap.EntryProcessor
Parameters:
entry - the Entry to process Note: if this method throws an exception, all modifications to the supplied entry or any other entries retrieved via the BackingMapContext.getBackingMapEntry(java.lang.Object) API will be rolled back leaving all underlying values unchanged.
Returns:
the result of the processing, if any

processAll

public java.util.Map processAll(java.util.Set setEntries)
Not supported.
Specified by:
processAll in interface InvocableMap.EntryProcessor
Parameters:
setEntries - a Set of InvocableMap.Entry objects to process
Returns:
a Map containing the results of the processing, up to one entry for each InvocableMap.Entry that was processed, keyed by the keys of the Map that were processed, with a corresponding value being the result of the processing for each key

Skip navigation links

Oracle® Fusion Middleware Java API Reference for Oracle Coherence
12c (12.1.3.0.0)

E47890-01


Copyright © 2000, 2014, Oracle and/or its affiliates. All rights reserved.