*/
    long deadline = System.nanoTime() + unit.toNanos(timeout);
    int added = 0;
    while (added < numElements) {
      // we could rely solely on #poll, but #drainTo might be more efficient when there are multiple
      // elements already available (e.g. LinkedBlockingQueue#drainTo locks only once)
      added += q.drainTo(buffer, numElements - added);

The benefit of raising an exception over `return`ing a value will be more evident in the section about Dependencies and Security.

This includes, for example:

* Email notifications sent after performing an action:
    * As connecting to an email server and sending an email tends to be "slow" (several seconds), you can return the response right away and send the email notification in the background.
* Processing data:

        logger.debug(indent + artifact + " (not setting artifactScope to: " + ignoredScope + "; local artifactScope "
                + artifact.getScope() + " wins)");

        // TODO better way than static? this might hide messages in a reactor
        if (!ignoredArtifacts.contains(artifact)) {
            logger.warn("\n\tArtifact " + artifact + " retains local artifactScope '" + artifact.getScope()

    INSTANCE;

    @Override
    public int compare(long[] left, long[] right) {
      int minLength = Math.min(left.length, right.length);
      for (int i = 0; i < minLength; i++) {
        int result = Longs.compare(left[i], right[i]);
        if (result != 0) {
          return result;
        }
      }
      return left.length - right.length;
    }

    @Override
    public String toString() {

    @ParametricNullness private final V right;

    static <V extends @Nullable Object> ValueDifference<V> create(
        @ParametricNullness V left, @ParametricNullness V right) {
      return new ValueDifferenceImpl<>(left, right);
    }

    private ValueDifferenceImpl(@ParametricNullness V left, @ParametricNullness V right) {
      this.left = left;
      this.right = right;
    }

    @Override

				// Subsequent reads will reuse this buffer.
				p.buf[bufIdx] = make([]byte, p.shardSize)
			}
			// For the last shard, the shardsize might be less than previous shard sizes.
			// Hence the following statement ensures that the buffer size is reset to the right size.
			p.buf[bufIdx] = p.buf[bufIdx][:p.shardSize]
			n, err := rr.ReadAt(p.buf[bufIdx], p.offset)
			if err != nil {
				switch {

  static int compareOrThrow(Comparable left, Comparable right) {
    return left.compareTo(right);
  }

  /** Needed to serialize sorted collections of Ranges. */
  private static class RangeLexOrdering extends Ordering<Range<?>> implements Serializable {
    static final Ordering<?> INSTANCE = new RangeLexOrdering();

    @Override
    public int compare(Range<?> left, Range<?> right) {
      return ComparisonChain.start()

            "five", 5,
            "six", 6,
            "seven", 7,
            "eight", 8),
        "one",
        1,
        "two",
        2,
        "three",
        3,
        "four",
        4,
        "five",
        5,
        "six",
        6,
        "seven",
        7,
        "eight",
        8);
    assertMapEquals(
        ImmutableMap.of(
            "one", 1,

## Do not Separate Schemas

Now, there are some cases where you might want to have the **same schema for input and output**.

Probably the main use case for this is if you already have some autogenerated client code/SDKs and you don't want to update all the autogenerated client code/SDKs yet, you probably will want to do it at some point, but maybe not right now.