Tape

关于

Tape 是由 Square, Inc. 为 Android 和 Java 提供的一系列队列相关类。

QueueFile 是一个闪电般快速、支持事务、基于文件的 FIFO（先进先出）队列。对实例的添加和移除操作复杂度均为 O(1) 且是原子性的。写入是同步的；数据将在操作返回前写入磁盘。底层文件结构设计成能够经受住进程甚至系统崩溃，并且如果在变更过程中抛出 I/O 异常，该变更将被中止。

ObjectQueue 表示任意对象的有序集合，它可以由文件系统支持（通过 QueueFile）或仅存在于内存中。

TaskQueue 是一个特殊的 ObjectQueue，它持有 Task 对象，这些对象具有可执行的概念。实例由外部执行器管理，该执行器准备并执行排队的任务。

<dependency>
    <groupId>com.squareup</groupId>
    <artifactId>tape</artifactId>
    <version>(insert latest)</version>
</dependency>

示例

要查看一个更完整的背景图像上传器示例（它扩展了以下两个示例），请参阅仓库中的示例 Android 应用程序。

Android 任务队列服务

在 Android 上使用时，Service 是 TaskQueue 的完美搭档，因为它允许在后台完成操作。如果用户正在上传新照片到他们喜欢的分享网站，Service 将迭代队列，直到所有上传任务成功完成。

/** Listener for starting the upload service when the queue has tasks. */
public class ImageQueueServiceListener implements ObjectQueue.Listener<ImageUploadTask> {
  private final Context context;

  public ImageQueueServiceStarter(Context context) {
    this.context = context;
  }

  @Override public void onAdd(ObjectQueue<ImageUploadTask> queue, ImageUploadTask task) {
    context.startService(new Intent(context, ImageQueueService.class));
  }

  @Override public void onRemove(ObjectQueue<ImageUploadTask> queue) {}
}

/** Service which iterates through pending upload tasks one-by-one. */
public class ImageQueueService extends Service implements ImageUploadTask.Callback {
  private TaskQueue<ImageUploadTask> queue;
  private boolean running;

  @Override public void onCreate() {
    super.onCreate();
    // Obtain TaskQueue here (e.g., through injection)
  }

  @Override public int onStartCommand(Intent intent, int flags, int startId) {
    executeNext();
    return START_STICKY;
  }

  public void executeNext() {
    if (running) return; // Only one task at a time.
    ImageUploadTask task = queue.peek();
    if (task != null) {
      task.execute(this);
      running = true;
      return;
    }
    stopSelf(); // We're done for now.
  }

  @Override public void imageUploadComplete() {
    running = false;
    queue.remove();
    executeNext();
  }
}

GSON 对象转换器

作为传统对象序列化的替代方案，GSON 使得将对象转换为 FileObjectQueue 可以写入磁盘的格式变得非常容易。这使得类在未来修改时具有更大的灵活性，同时也提供了人类可读的存储格式。

/** Converter which uses GSON to serialize instances of class T to disk. */
public class GsonConverter<T> implements FileObjectQueue.Converter<T> {
  private final Gson gson;
  private final Class<T> type;

  public GsonConverter(Gson gson, Class<T> type) {
    this.gson = gson;
    this.type = type;
  }

  @Override public T from(byte[] bytes) {
    Reader reader = new InputStreamReader(new ByteArrayInputStream(bytes));
    return gson.fromJson(reader, type);
  }

  @Override public void toStream(T object, OutputStream bytes) throws IOException {
    Writer writer = new OutputStreamWriter(bytes);
    gson.toJson(object, writer);
    writer.close();
  }
}

贡献

如果您想为 Tape 贡献代码，可以通过 GitHub 进行，方法是 fork 仓库并发送 pull request。

提交代码时，请尽最大努力遵循现有的约定和风格，以保持代码尽可能可读。此外，请确保您的代码可以通过运行 mvn clean verify 编译。编译期间的 Checkstyle 失败表示您的风格存在错误，可以在 target/checkstyle-result.xml 文件中查看。

在您的代码被项目接受之前，您还必须签署个人贡献者许可协议（CLA）。