sourcePos += bytesToRead
        return bytesToRead
      }

      // Read from upstream. This always reads a full buffer: that might be more than what the
      // current call to Source.read() has requested.
      try {
        val upstreamBytesRead = upstream!!.read(upstreamBuffer, bufferMaxSize)

        // If we've exhausted upstream, we're done.
        if (upstreamBytesRead == -1L) {

   * specified element (or equivalently, if this queue changed as a result of the call).
   *
   * @param o element to be removed from this queue, if present
   * @return {@code true} if this queue changed as a result of the call
   */
  @CanIgnoreReturnValue // pushed down from class to method
  @Override
  public boolean remove(@Nullable Object o) {

    private final Callable<T> delegate;

    public WrappedCallable(Callable<T> delegate) {
      this.delegate = delegate;
    }

    @Override
    public T call() throws Exception {
      return delegate.call();
    }
  }

  private static final class WrappedRunnable implements Runnable {
    private final Runnable delegate;

    public WrappedRunnable(Runnable delegate) {

  // via delegate()); it seems inappropriate to throw ISE on this method.
  @Override
  public int hashCode() {
    return delegate.hashCode();
  }

  private void validate() {
    // Don't use checkState(), because we don't want the overhead of generating the error message
    // unless it's actually going to be used; validate() is called for all set method calls, so it
    // needs to be fast.

type conn interface {
	// Version returns version information about the KMS.
	//
	// TODO(aead): refactor this API call. It does not account
	// for multiple endpoints.
	Version(context.Context) (string, error)

	// APIs returns a list of APIs supported by the KMS server.
	//
	// TODO(aead): remove this API call. It's hardly useful.
	APIs(context.Context) ([]madmin.KMSAPI, error)

	// Stat returns the current KMS status.

@SuppressWarnings("JUnit4ClassUsedInJUnit3")
public abstract class AbstractListIndexOfTester<E> extends AbstractListTester<E> {
  /** Override to call {@code indexOf()} or {@code lastIndexOf()}. */
  protected abstract int find(@Nullable Object o);

  /** Override to return "indexOf" or "lastIndexOf()" for use in failure messages. */
  protected abstract String getMethodName();

      BundleTaskExtension::class.java,
      jarTask,
    )
  bundleExtension.run {
    setClasspath(osgi.compileClasspath + sourceSets["main"].compileClasspath)
    bnd(*bndProperties)
  }
  // Call the convention when the task has finished, to modify the jar to contain OSGi metadata.
  jarTask.doLast {
    bundleExtension.buildAction().execute(this)
  }
}

val Project.sourceSets: SourceSetContainer

So we are going to use that same knowledge to document how the *external API* should look like... by creating the *path operation(s)* that the external API should implement (the ones your API will call).

/// tip

When writing the code to document a callback, it might be useful to imagine that you are that *external developer*. And that you are currently implementing the *external API*, not *your API*.

      } catch (RuntimeException e) {
        // Don't call getMessage or toString() on the exception, in case the exception thrown by the
        // subclass is implemented with bugs similar to the subclass.
        pendingDescription = "Exception thrown from implementation: " + e.getClass();
      }
      // The future may complete during or before the call to getPendingToString, so we use null

import java.io.FilterInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.Random;

/** Returns a random portion of the requested bytes on each call. */
class RandomAmountInputStream extends FilterInputStream {
  private final Random random;

  public RandomAmountInputStream(InputStream in, Random random) {
    super(checkNotNull(in));