com.github.phantomthief.collection.BufferTrigger Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of buffer-trigger Show documentation
A buffer with trigger
There is a newer version: 0.2.5
package com.github.phantomthief.collection;

import java.util.concurrent.ConcurrentHashMap;

import com.github.phantomthief.collection.impl.BatchConsumeBlockingQueueTrigger;
import com.github.phantomthief.collection.impl.BatchConsumerTriggerBuilder;
import com.github.phantomthief.collection.impl.GenericBatchConsumerTriggerBuilder;
import com.github.phantomthief.collection.impl.GenericSimpleBufferTriggerBuilder;
import com.github.phantomthief.collection.impl.SimpleBufferTrigger;
import com.github.phantomthief.collection.impl.SimpleBufferTriggerBuilder;

/**
 * 一个支持自定义消费策略的本地缓存.
 * 用于本地缓存指定条目数据集，定时进行批处理或聚合计算；可用于埋点聚合计算，点赞计数等不追求强一致的业务场景.
 * 
大多数场景推荐调用{@link #simple()}来构造{@link BufferTrigger}.
 *
 * @author w.vela
 */
public interface BufferTrigger extends AutoCloseable {

    /**
     * 将需要定时处理的元素推入缓存.
     *
     * @throws IllegalStateException 当实例被关闭时，调用该方法可能会引起该异常.
     */
    void enqueue(E element);

    /**
     * 手动触发一次缓存消费.
     * 
一般处于缓存关闭方法{@link #close()}实现中.
     */
    void manuallyDoTrigger();

    /**
     * 获取当前缓存中未消费元素个数.
     */
    long getPendingChanges();

    /**
     * 快捷创建{@link GenericSimpleBufferTriggerBuilder}建造器，用于构造{@link SimpleBufferTrigger}实例.
     * 

     * 推荐用该方法构造{@link SimpleBufferTrigger}实例，适用用大多数场景
     *
     * @param  元素类型
     * @param  持有元素的容器类型，如使用默认容器实现（不指定 {@link GenericSimpleBufferTriggerBuilder#setContainerEx}），默认为 {@link ConcurrentHashMap#newKeySet()}，
     * 
此时本泛型可以考虑设置为 Set<E>
     * 
注意，强烈不建议使用默认容器，任何时候，都应该优先考虑自行设计容器类型!
     * @return {@link GenericSimpleBufferTriggerBuilder} 实例
     */
    static  GenericSimpleBufferTriggerBuilder simple() {
        return new GenericSimpleBufferTriggerBuilder<>(SimpleBufferTrigger.newBuilder());
    }

    /**
     * 该方法即将废弃，可更换为{@link #simple()}.
     */
    @Deprecated
    static SimpleBufferTriggerBuilder simpleTrigger() {
        return SimpleBufferTrigger.newBuilder();
    }

    /**
     * 提供自带背压(back-pressure)的简单批量归并消费能力.
     * 

     *
     * 

     * FIXME: 高亮注意，目前 {@link #simple()} 也提供了背压能力 {@link GenericSimpleBufferTriggerBuilder#enableBackPressure()}
     * 所以本模式的意义已经小的多，如果没特殊情况，可以考虑都切换到 {@link SimpleBufferTrigger} 版本.
     */
    static  GenericBatchConsumerTriggerBuilder batchBlocking() {
        return new GenericBatchConsumerTriggerBuilder<>(
                BatchConsumeBlockingQueueTrigger.newBuilder());
    }

    /**
     * 该方法即将废弃，请使用{@link #batchBlocking()}替代.
     */
    @Deprecated
    static BatchConsumerTriggerBuilder