基础使用 - xuexiangjys/XTask GitHub Wiki

XTask 作为对外统一的API入口，所有常用的方法都能从中找到。

打开调试模式

当需要定位问题，需要进行调试时，可打开调试模式，这样便可开启框架的日志。

XTask.debug(true);

XTask的API介绍

方法名	描述
debug	设置是否打开调试
setLogger	自定义日志打印
setIsLogThreadName	设置是否打印任务执行所在的线程名，默认false
getTaskChain	获取任务链执行引擎
getTask	获取简化的任务
getTaskBuilder	获取简化任务的构建者
getConcurrentGroupTask	获取并行任务组
getSerialGroupTask	获取串行任务组
cancelTaskChain	取消指定任务链执行
cancelAllTaskChain	取消所有任务链执行
postToMain	执行任务到主线程
postToMainDelay	延迟执行任务到主线程
submit	执行普通异步任务
emergentSubmit	执行紧急异步任务
backgroundSubmit	执行后台异步任务
ioSubmit	执行io耗时的异步任务
groupSubmit	执行分组异步任务
schedule	执行延期任务
scheduleAtFixedRate	执行周期任务（固定间期）
scheduleWithFixedDelay	执行周期任务（固定延期）

如何执行一条任务链

下面是一整个完整的例子：

// 1.创建一条任务链（必须）
final TaskChainEngine engine = XTask.getTaskChain();
// 2.设置任务链的初始化参数（可选）
engine.setTaskParam(TaskParam.get("chainName", engine.getName()));
TaskParam taskParam = TaskParam.get("param1", 100)
        .put("param2", true);
// 3.创建多个任务，并向任务链中添加（必须）
XTaskStep taskStep = XTask.getTask(new TaskCommand() {
    @Override
    public void run() {
        ITaskParam param = getTaskParam();
        Log.e(TAG, getName() + "  start, param1:" + param.get("param1") + ", chainName:" + param.get("chainName"));
        param.put("param1", 200);
        param.put("param3", "this is param3!");
    }
}, taskParam);
engine.addTask(taskStep)
        .addTask(XTask.getTask(new TaskCommand() {
            @Override
            public void run() {
                ITaskParam param = getTaskParam();
                Log.e(TAG, getName() + "  start, param1:" + param.get("param1") + ", param3:" + param.get("param3"));
                param.put("param2", false);
            }
        }));
// 4.设置任务链执行回调（可选）
ICanceller canceller = engine.setTaskChainCallback(new TaskChainCallbackAdapter() {
    @Override
    public void onTaskChainCompleted(@NonNull ITaskChainEngine engine, @NonNull ITaskResult result) {
        Log.e(TAG, "task chain completed, thread:" + Thread.currentThread().getName());
        Map<String, Object> data = result.getDataStore().getData();
        for (Map.Entry<String, Object> entry : data.entrySet()) {
            Log.e(TAG, "key:" + entry.getKey() + ", value:" + entry.getValue());
        }
    }
// 5.任务链执行（必须）
}).start();

1.创建一条任务链.（必须）

TaskChainEngine engine = XTask.getTaskChain();

2.设置任务链的初始化参数.（可选）

engine.setTaskParam(TaskParam.get("chainName", engine.getName()));

3.创建多个任务，并向任务链中添加.（必须）

// 设置任务初始化参数
TaskParam taskParam = TaskParam.get("param1", 100)
        .put("param2", true);
XTaskStep taskStep = XTask.getTask(new TaskCommand() {
    @Override
    public void run() {
        // ...执行任务
    }
}, taskParam);
engine.addTask(taskStep)
        .addTask(XTask.getTask(new TaskCommand() {
            @Override
            public void run() {
                // ...执行任务
            }
        }));

【注意】对于任务执行完成，需要注意以下两点：

如果任务执行成功，就调用notifyTaskSucceed，任务执行失败，就调用notifyTaskFailed。这里任务无论成功还是失败，只要执行完成都需要调用notifyTaskXXX通知任务链该任务完成，否则任务将无法正常执行。
TaskCommand和SimpleTaskStep默认提供了自动通知执行结果的功能，但是AbstractTaskStep没有提供，需要手动通知。

4.设置任务链执行回调.（可选）

调用setTaskChainCallback设置任务链执行回调。

engine.setTaskChainCallback(new TaskChainCallbackAdapter() {

    @Override
    public boolean isCallBackOnMainThread() {
        // 回调是否返回主线程, 默认是true
        return false;
    }
    @Override
    public void onTaskChainStart(@NonNull ITaskChainEngine engine) {
        Log.e(TAG, "task chain start");
    }
    @Override
    public void onTaskChainCompleted(@NonNull ITaskChainEngine engine, @NonNull ITaskResult result) {
        Log.e(TAG, "task chain completed, thread:" + Thread.currentThread().getName());
    }
    @Override
    public void onTaskChainError(@NonNull ITaskChainEngine engine, @NonNull ITaskResult result) {
        Log.e(TAG, "task chain error");
    }
})

5.任务链执行.（必须）

调用start执行任务链。

ICanceller canceller = engine.start();

任务创建

创建任务有两种方式：

通过XTask.getTask构建
继承SimpleTaskStep/AbstractTaskStep实现任务的自定义

通过XTask创建

通过XTask.getTask, 传入对应的属性进行构建

属性名	描述	默认值
name	任务步骤名称	XTaskStep-N(N为自增数）
command	任务执行内容	/
threadType	线程执行类型	ThreadType.ASYNC
taskParam	任务参数	new TaskParam()
taskHandler	任务处理者	null
isAutoNotify	是否自动通知任务执行结果	true

XTaskStep taskStep = XTask.getTask(new TaskCommand() {
    @Override
    public void run() {
        // todo
    }
}, ThreadType.ASYNC, taskParam);

通过继承创建

通过继承SimpleTaskStep或者AbstractTaskStep实现具体功能。

public class StepATask extends SimpleTaskStep {

    @Override
    public void doTask() throws Exception {
        // todo
        // 不需要手动通知任务链任务完成
    }
}

public class StepBTask extends AbstractTaskStep {

    @Override
    public void doTask() throws Exception {
        // todo
        // 需手动通知任务链任务完成
        notifyTaskSucceed(TaskResult.succeed());
    }

    @Override
    public String getName() {
        return "StepATask";
    }
}

任务执行原则

每一个任务都是依托于任务链进行流程控制。任何任务都需要遵循以下原则：

任何任务无论失败还是成功，都需要调用notifyTaskSucceed或者notifyTaskFailed去通知任务链任务的完成情况。TaskCommand和SimpleTaskStep默认提供了自动通知执行结果的功能。
一旦任务链中某个任务执行失败，整个链路都停止工作。

任务类型	任务执行说明
TaskCommand	自动通知执行结果。如需手动通知，只需设置`isAutoNotify`为false即可
SimpleTaskStep	自动通知执行结果。如需手动通知，只需重写`isAutoNotify`方法为false即可
AbstractTaskStep	需手动通知执行结果

TaskCommand手动通知执行结果

在通过XTask.getTask传入TaskCommand构建Task的时候，设置isAutoNotify为false即可手动通知执行结果。

final TaskChainEngine engine = XTask.getTaskChain();
for (int i = 0; i < 5; i++) {
    int finalI = i;
    engine.addTask(XTask.getTask(new TaskCommand() {
        @Override
        public void run() {
            try {
                Thread.sleep(1000);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
            if (finalI == 2) {
                notifyTaskFailed(404, "任务执行失败!");
            } else {
                notifyTaskSucceed(TaskResult.succeed());
            }
        }
    }, false)); // 设置手动通知执行结果
}
engine.start();

SimpleTaskStep手动通知执行结果

重写SimpleTaskStep的isAutoNotify方法为false即可手动通知执行结果。

public class StepATask extends SimpleTaskStep {

    @Override
    public void doTask() throws Exception {
        // todo
        // 手动通知任务链任务完成
        notifyTaskSucceed();
    }

    @Override
    protected boolean isAutoNotify() {
        return false;
    }
}

参数传递

任何TaskStep我们都可以通过getTaskParam获取任务参数和任务执行结果ITaskParam。
上一个TaskStep保存处理过的任务参数会自动带入到下一个TaskStep中去，因此最后一个TaskStep拥有之前所有任务的参数数据。

XTask.getTask(new TaskCommand() {
    @Override
    public void run() {
        ITaskParam param = getTaskParam();
        Log.e(TAG, getName() + "  start, param1:" + param.get("param1") + ", param3:" + param.get("param3"));
        param.put("param2", false);
    }
})

线程控制

设置任务的threadType类型，即可完成对任务运行线程的控制。目前支持6种线程处理方式。

类型	描述	线程池构成
MAIN	主线程（UI线程）	/
ASYNC	异步线程（开子线程，普通线程池）	核心线程数和最大线程为CPU数，0s keepTime，LinkedBlockingQueue（128），线程优先级5
ASYNC_IO	异步线程（开子线程，io线程池）	核心线程数和最大线程为(2*CPU数+1)，30s keepTime，LinkedBlockingQueue（128），线程优先级5
ASYNC_EMERGENT	异步线程（开子线程，紧急线程池）	核心线程数为2，最大线程为∞，60s keepTime，SynchronousQueue（不阻塞），线程优先级10
ASYNC_BACKGROUND	异步线程（开子线程，优先级较低线程池）	核心线程数和最大线程为2，0s keepTime，LinkedBlockingQueue（128），线程优先级1
SYNC	同步线程（直接执行）	/

// 1.构造时传入线程
XTaskStep taskStep = XTask.getTask(new SimpleTaskCommand(1000), ThreadType.ASYNC_EMERGENT);
// 2.设置线程的方法
taskStep.setThreadType(ThreadType.ASYNC_IO);