1 /*
2 * Copyright (C) 2010, Google Inc. and others
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Distribution License v. 1.0 which is available at
6 * https://www.eclipse.org/org/documents/edl-v10.php.
7 *
8 * SPDX-License-Identifier: BSD-3-Clause
9 */
10
11 package org.eclipse.jgit.lib;
12
13 import java.io.IOException;
14
15 import org.eclipse.jgit.errors.MissingObjectException;
16
17 /**
18 * Queue to open objects asynchronously.
19 *
20 * A queue may perform background decompression of objects and supply them
21 * (possibly out-of-order) to the application.
22 *
23 * @param <T>
24 * type of identifier supplied to the call that made the queue.
25 */
26 public interface AsyncObjectLoaderQueue<T extends ObjectId> extends
27 AsyncOperation {
28
29 /**
30 * Position this queue onto the next available result.
31 *
32 * Even if this method returns true, {@link #open()} may still throw
33 * {@link org.eclipse.jgit.errors.MissingObjectException} if the underlying
34 * object database was concurrently modified and the current object is no
35 * longer available.
36 *
37 * @return true if there is a result available; false if the queue has
38 * finished its input iteration.
39 * @throws org.eclipse.jgit.errors.MissingObjectException
40 * the object does not exist. If the implementation is retaining
41 * the application's objects {@link #getCurrent()} will be the
42 * current object that is missing. There may be more results
43 * still available, so the caller should continue invoking next
44 * to examine another result.
45 * @throws java.io.IOException
46 * the object store cannot be accessed.
47 */
48 boolean next() throws MissingObjectException, IOException;
49
50 /**
51 * Get the current object, null if the implementation lost track.
52 *
53 * @return the current object, null if the implementation lost track.
54 * Implementations may for performance reasons discard the caller's
55 * ObjectId and provider their own through {@link #getObjectId()}.
56 */
57 T getCurrent();
58
59 /**
60 * Get the ObjectId of the current object. Never null.
61 *
62 * @return the ObjectId of the current object. Never null.
63 */
64 ObjectId getObjectId();
65
66 /**
67 * Obtain a loader to read the object.
68 *
69 * This method can only be invoked once per result
70 *
71 * Due to race conditions with a concurrent modification of the underlying
72 * object database, an object may be unavailable when this method is
73 * invoked, even though next returned successfully.
74 *
75 * @return the ObjectLoader to read this object. Never null.
76 * @throws MissingObjectException
77 * the object does not exist. If the implementation is retaining
78 * the application's objects {@link #getCurrent()} will be the
79 * current object that is missing. There may be more results
80 * still available, so the caller should continue invoking next
81 * to examine another result.
82 * @throws java.io.IOException
83 * the object store cannot be accessed.
84 */
85 ObjectLoader open() throws IOException;
86 }