com.tangosol.util.processor.StreamingAsynchronousProcessor 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.Objects;

import java.util.function.Consumer;


/**
 * An {@link EntryProcessor EntryProcessor} wrapper class that allows for
 * an asynchronous invocation of the underlying processor. Unlike
 * {@link AsynchronousProcessor}, this implementation does not collect the
 * results of the underlying entry processor execution, but simply streams
 * partial results to the provided partial results callback.
 * 
 * This allows for a much lower memory overhead if the complete result set does
 * not to be realized on the client.
 * 

 * It's very important that the overriding implementations of
 * {@link #onComplete}, {@link #onResult} and {@link #onException},
 * and provided callbacks 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
 * @see SingleEntryAsynchronousProcessor
 *
 * @author as  2015.01.28
 */
public class StreamingAsynchronousProcessor
        extends AbstractAsynchronousProcessor
    {
    /**
     * Construct a StreamingAsynchronousProcessor for a given processor and one or more callbacks.
     * 

     * Important Note: All provided callbacks must be non-blocking.
     * For example, any use of {@link NamedCache} API is completely disallowed.
     *
     * @param processor     the underlying {@link EntryProcessor}
     * @param onPartial     a user-defined callback that will be called for each
     *                      partial result
     */
    public StreamingAsynchronousProcessor(EntryProcessor processor,
                                          Consumer> onPartial)

        {
        this(processor, Thread.currentThread().hashCode(), onPartial);
        }

    /**
     * Construct a StreamingAsynchronousProcessor for a given processor and one or more callbacks.
     * 
     * Important Note: All provided callbacks must be non-blocking.
     * For example, any use of {@link NamedCache} API is completely disallowed.
     *
     * @param processor     the underlying {@link EntryProcessor}
     * @param iUnitOrderId  the unit-of-order id for this processor
     * @param onPartial     a user-defined callback that will be called for each
     *                      partial result
     */
    public StreamingAsynchronousProcessor(EntryProcessor processor, int iUnitOrderId,
                                          Consumer> onPartial)
        {
        super(processor, iUnitOrderId);

        Objects.requireNonNull(onPartial);
        f_onPartial = onPartial;
        }

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

    @Override
    public void onResult(Map.Entry entry)
        {
        f_onPartial.accept(entry);
        }

    @Override
    public void onException(Throwable eReason)
        {
        }

    @Override
    public void onComplete()
        {
        complete(() -> null);
        }

    // ---- data members ----------------------------------------------------

    /**
     * The user-provided callback that will be invoked for each partial result.
     */
    protected final Consumer> f_onPartial;
    }