进阶使用教程

以下内容对开发过程中较为关键的部分做出介绍，完整开发者文档下载链接：开发者接入文档.pdf

一、使用原生方式同步启动任务

1 加载比对库

将所有要作为比对库的文件放到一个文件夹中（支持doc、docx、pdf、rtf、txt格式），实例化PaperLibrary时将文件夹路径传入构造方法。

LocalPaperLibrary paperLibrary = LocalPaperLibrary.load(new File("对比库文件夹路径"));

注：加载比对库会花费一定时间，通常只需要在服务启动的时候加载一次，后续的所有查重操作都不需要再重新加载比对库。

2 加载待查重的文件

Paper paper = Paper.load(new File("文件路径")); //加载单个文件

将待查重的文件加载为Paper。Paper支持多种加载方式，可以通过文件、字符串、输入流加载，也支持批量加载。本例中以通过文件加载为例，其它用法请阅读“重要高级接口介绍”。

3 启动查重任务

//构建并启动任务
CheckTask checkTask = CheckManager.INSTANCE
        .getCheckTaskBuilder() //获取查重任务构建器
        .addLibrary(paperLibrary) //添加比对库。可以添加多个
        .addCheckPaper(paper) //添加待查文本。可以添加多个
        .build(); //构建任务，返回checkTask对象
checkTask.start(); //启动任务线程
checkTask.join(); //等待查重结束（阻塞）

该方式为同步启动查重任务，并通过join方法等待查重任务结束。SDK支持异步调用，

注意：待查文本和比对库中的文本如果完全相同，将会自动跳过，不进行查重比对。测试时请不要使用完全相同的两个文本进行查重。

4 保存查重报告

查重任务结束后可以通过以下方式将查重报告保存为html文件，SDK可以生成三种查重报告。

checkTask.getReporters().get(0).saveAsFile("C:\\Report\\report1.html", ReportType.TEXT_WITH_CITATION); //保存全文标红查重报告
checkTask.getReporters().get(0).saveAsFile("C:\\Report\\report2.html", ReportType.TEXT_WITH_ORIGINAL); //保存原文对照查重报告
checkTask.getReporters().get(0).saveAsFile("C:\\Report\\report3.html", ReportType.SAMPLE); //保存简洁查重报告

getReporters方法返回一个查重任务中所有待查文本的查重结果列表。本例中只添加了一个待查文本，因此直接通过get(0)获取到对应的查重结果。

当然，您可以不将结果保存为文件，直接通过接口获取到查重结果。如：

String reportId = reporter.getReportId(); //获取查重报告id
String copyRate = reporter.getCopyRate(); //获取总重复率
String copyWords = reporter.getCopyWords(); //获取重复字数

查重报告的样式可以通过接口进行一定程度的自定义，详请阅读本文档的“详细文档-接口文档-自定义查重报告样式”部分；同时，查重报告的所有内容都可以在代码中以接口的方式获取到，详请阅读开发者接入文档的“详细文档-接口文档-获取查重报告的元数据”部分。

二、通过CheckState观察者异步处理查重任务

通常情况下根据比对库的大小、待查文本的字数、计算机CPU繁忙程度等因素的不同，需要数秒至数分钟才能完成一次查重任务。因此查重任务的异步处理就显得尤为重要。通过实现CheckState接口，可以实现查重任务的异步处理。

CheckState接口中包含start、finish、fail三个方法，分别对应查重任务提交后的启动、完成和失败。泛型T对应查重任务提交时传递的上下文信息的数据类型。

以下是一个简单的CheckState接口的实现：

public class CheckStateImp implements CheckState<String> {

    @Override
    public void taskStart(String uid, List<Paper> toCheckPapers, String info) {
        System.out.println("task start:" + uid);
    }

    @Override
    public void taskFinish(String uid, List<Paper> toCheckPapers, List<Reporter> reporters, List<Paper> failedPapers, String info) {
        System.out.println("task finish:" + uid);
    }

    /**
     * 开始查重时回调此函数
     *
     * @param uid   查重任务id
     * @param paper 被查Paper
     * @param info  自定义上下文信息
     */
    @Override
    public void paperStart(String uid, Paper paper, String info) {
        System.out.println("paper start:" + uid);
    }


    /**
     * 查重完毕回调此函数
     *
     * @param uid      查重任务id
     * @param reporter 查重报告
     * @param info     自定义上下文信息
     */
    @Override
    public void paperSuccess(String uid, Reporter reporter, String info) {
        System.out.println("paper success:" + uid);
        //如果使用本地比对库，可直接保存两种类型的查重报告
        try {
            reporter.saveAsFile("D:\\Desktop\\" + uid + "-1.html", ReportType.TEXT_WITH_CITATION); //保存查重报告（全文标红）
            reporter.saveAsFile("D:\\Desktop\\" + uid + "-2.html", ReportType.TEXT_WITH_ORIGINAL); //保存查重报告（原文对照）
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    /**
     * 查重失败后回调
     *
     * @param uid   查重任务id
     * @param paper 失败的Paper
     * @param code  错误码
     * @param e     错误信息
     * @param info  自定义上下文信息
     */
    @Override
    public void paperFailed(String uid, Paper paper, int code, Throwable e, String info) {
        e.printStackTrace();
        System.out.println("paper fail:" + uid + " cdoe:" + code + " msg:" + e.getMessage());
    }

}
//CheckState实现范例

实现了CheckState接口后，我们就可以通过以下方法启动查重任务，并使用setCheckState方法将该CheckState注册到查重任务中。这样在查重任务的各个状态就会回调CheckState的不同方法。

//构建并启动任务
CheckManager.INSTANCE
        .getCheckTaskBuilder() //获取构建者
        .setUid("1") //设置任务id。如不设置会随机生成uuid
        .addCheckState(new CheckStateImp(), "test") //设置回调处理和自定义信息。如不设置将无法收到回调
        .addLibrary(paperLibrary) //设置比对库
        .addCheckPaper(toCheckPaper) //设置待查Paper
        .build() //构建任务
        .submit(); //启动任务。submit：将任务提交到线程池中。start：直接启动任务

submit后任务将提交到线程池中，任务状态改变时会主动回调CheckState中对应的方法，无需再通过join等待任务结束。

三、实例化文本对象（Paper）

在SDK中，无论是待查重的文件还是用于充当比对库的文件，都需要实例化为Paper对象后再进行后续的处理。本地比对库LocalPaperLibrary可以看作是一个包含Paper对象的集合。Paper对象可以通过File对象实例化，也可以通过文本内容实例化。

①通过File对象实例化

Paper paper = Paper.load(new File("文件路径"));

这种加载方式需要传入一个File对象，传入后将根据File对象中文件路径的拓展名识别文件类型，并进行加载。SDK只支持doc、docx、pdf、rtf、txt格式的文件，其中txt格式的加载效率最高，pdf格式的加载效率最低。

②通过File对象实例化，并指定文件类型

Paper paper = Paper.load(new File("文件路径"), FileType.TXT);

这种加载方式需要传入两个参数，包含一个File对象以及文件类型FileType。此时将根据传入的文件类型进行加载。这种加载方式适合File对象中不包含文件路径，或文件路径中的文件名不包含拓展名的情况。第二个参数FileType是枚举类型。

③通过文本实例化

Paper paper = Paper.load("文本内容");

通过文件的文本内容加载Paper对象。如对用户输入的文本进行查重，用户的输入只是一串文本，这种情况下可以直接用文本内容构建Paper对象进行查重。

四、为本文对象补充额外信息

对于每一个Paper对象，包含id、标题、作者、其它信息四项可选信息，这四项信息的设置不会影响查重结果。id可由开发者按需标记、使用，用以唯一标识一个Paper对象，不会在查重报告中展示；其余三项项信息设置后会在查重报告中进行展示。如果不设置这些信息，将默认使用文件名作为标题，其它信息为空。有以下几种方式可以对这四项信息进行设置。

①通过set方法直接设置

paper.setId("001").setTitle("标题").setAuthor("作者").setInfo("其它需要展示的信息");

可以通过set方法连续设置id、标题、作者、来源、年份等信息。

②通过格式化文件名设置

通过File对象加载Paper对象时，如果文件名中包含分隔符“@”且数量符合以下任一种规则，将自动从文件名中读取标题、作者、来源和年份信息。

1）如果文件名中包含1个分隔符，sdk会将文件名按分隔符分割为数组后依次读取为id、标题，如文件名为“001@标题.docx”；

2）如果文件名中包含2个分隔符，sdk会将文件名按分隔符分割为数组后依次读取为id、标题、作者，如文件名为“001@标题@作者.docx”；

3）如果文件名中包含3个分隔符，sdk会将文件名按分隔符分割为数组后依次读取为id、标题、作者、其它信息，如文件名为“001@标题@作者@其它需要展示的信息.docx”；

4）如果文件名中不包含分隔符，sdk会将文件名读取为标题，如文件名为“标题.docx”。

另：“@”只是SDK的默认分割符，分隔符可由开发者自行修改，修改方式参见“详细文档-接口文档-高级配置项”部分。

五、为Paper设置Payload

Payload可用于传递上下文信息，也可以用于为Paper补充不希望在查重报告中展示的信息。对于每一个Paper对象，可以设置一个Payload，Payload不会展示到查重报告中，但可以用来存储额外信息或上下文信息。Payload可以是任意对象，但该对象必须实现了Serializable接口。设置payload后，可以通过get方法获取。

paper.setPayload("001");
Object payload = paper.getPayload();

六、开发者接入文档

本篇内容中已经对涉及项目开发的少量高级特性进行了介绍，详细的接口和参数说明请下载完整的开发者接入文档.pdf查阅。

七、完整实例代码

参见GitHub链接中的Sample部分。