com.tangosol.util.processor.SingleEntryAsynchronousProcessor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of coherence Show documentation
Oracle Coherence Community Edition
There is a newer version: 24.09
/*
 * Copyright (c) 2000, 2020, Oracle and/or its affiliates.
 *
 * Licensed under the Universal Permissive License v 1.0 as shown at
 * http://oss.oracle.com/licenses/upl.
 */
package com.tangosol.util.processor;


import com.tangosol.net.NamedCache;

import com.tangosol.util.InvocableMap.EntryProcessor;

import java.util.Map;

import java.util.concurrent.Future;


/**
 * An {@link EntryProcessor EntryProcessor} wrapper class that allows for
 * an asynchronous invocation of the underlying processor against a single
 * cache entry. When used as a {@link Future} (without extending), this
 * implementation will collect the results of asynchronous invocation,
 * providing the {@link Future#get result} semantics identical to the
 * {@link EntryProcessor#process EntryProcessor.process} contract.
 * 
 * More advanced use would require extending this class and overriding
 * {@link #onResult}, {@link #onComplete}, and {@link #onException} methods.
 * 

 * It's very important that the overriding implementations of these methods
 * must be non-blocking. For example, any use of {@link NamedCache} API is
 * completely disallowed, with the only exception of asynchronous agents
 * with disabled flow control.
 * 

 * The underlying entry processor is guaranteed to have been fully executed when
 * {@link #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.
 *
 * @param   the type of the Map entry key
 * @param   the type of the Map entry value
 * @param   the type of value returned by the EntryProcessor
 *
 * @see AsynchronousProcessor
 *
 * @author as  2015.01.26
 * @since 12.2.1
 */
public class SingleEntryAsynchronousProcessor
        extends AbstractAsynchronousProcessor
    {
    /**
     * Construct a SingleEntryAsynchronousProcessor for a given processor.
     *
     * @param processor  the underlying {@link EntryProcessor}
     */
    public SingleEntryAsynchronousProcessor(EntryProcessor processor)
        {
        this(processor, Thread.currentThread().hashCode());
        }

    /**
     * Construct a SingleEntryAsynchronousProcessor for a given processor.
     *
     * @param processor     the underlying {@link EntryProcessor}
     * @param iUnitOrderId  the unit-of-order id for this processor
     */
    public SingleEntryAsynchronousProcessor(EntryProcessor processor,
                                            int iUnitOrderId)
        {
        super(processor, iUnitOrderId);
        }

    // ----- AsynchronousProcessor API ---------------------------------------

    @Override
    public void onResult(Map.Entry entry)
        {
        m_entry = entry;
        }

    @Override
    public void onException(Throwable eReason)
        {
        m_eReason = eReason;
        }

    @Override
    public void onComplete()
        {
        Throwable eReason = m_eReason;
        if (eReason == null)
            {
            complete(() -> m_entry == null ? null : m_entry.getValue());
            }
        else
            {
            completeExceptionally(eReason);
            }
        }

    // ----- data fields ----------------------------------------------------

    /**
     * Reason for the failed operation.
     */
    protected volatile Throwable m_eReason;

    /**
     * The result of entry processor invocation.
     */
    protected Map.Entry m_entry;
    }