* the License.
 */

package com.google.common.collect;

import static java.util.Arrays.sort;

import com.google.caliper.BeforeExperiment;
import com.google.caliper.Benchmark;
import com.google.caliper.Param;
import java.util.Arrays;
import java.util.Comparator;
import java.util.Random;

/**

 */

package com.google.common.collect;

import static com.google.common.base.Preconditions.checkArgument;
import static java.util.Collections.sort;

import com.google.caliper.BeforeExperiment;
import com.google.caliper.Benchmark;
import com.google.caliper.Param;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Random;
import java.util.Set;

 */

package com.google.common.collect;

import static com.google.common.base.Preconditions.checkArgument;
import static java.util.Collections.sort;

import com.google.caliper.BeforeExperiment;
import com.google.caliper.Benchmark;
import com.google.caliper.Param;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Random;
import java.util.Set;

 *
 * <p>{@code ByteSink} provides two kinds of methods:
 *
 * <ul>
 *   <li><b>Methods that return a stream:</b> These methods should return a <i>new</i>, independent
 *       instance each time they are called. The caller is responsible for ensuring that the
 *       returned stream is closed.
 *   <li><b>Convenience methods:</b> These are implementations of common operations that are

    /**
     * Puts the specified data into the cache. <strong>Warning:</strong> The cache will directly save the provided
     * reference. If the cached data is mutable, i.e. could be modified after being put into the cache, the caller is
     * responsible for creating a copy of the original data and store the copy in the cache.
     *
     * @param request The repository request from which this cache was retrieved, must not be {@code null}.

     * existing values in the execution request that are controlled by the toolchains. Hence, it is expected that this
     * method is called on a new/empty execution request before the caller mutates it to fit its needs.
     *
     * @param request The execution request to populate, must not be {@code null}.
     * @param toolchains The toolchains to copy into the execution request, may be {@code null}.

 *
 * <p>{@code CharSink} provides two kinds of methods:
 *
 * <ul>
 *   <li><b>Methods that return a writer:</b> These methods should return a <i>new</i>, independent
 *       instance each time they are called. The caller is responsible for ensuring that the
 *       returned writer is closed.
 *   <li><b>Convenience methods:</b> These are implementations of common operations that are

   * elements than the collection), the element in the array immediately following the end of the
   * collection is set to {@code null}. This is useful in determining the length of the collection
   * <i>only</i> if the caller knows that the collection does not contain any null elements.
   *
   * <p>This method returns the elements in the order they are returned by the collection's
   * iterator.
   *

   * elements than the collection), the element in the array immediately following the end of the
   * collection is set to {@code null}. This is useful in determining the length of the collection
   * <i>only</i> if the caller knows that the collection does not contain any null elements.
   *
   * <p>This method returns the elements in the order they are returned by the collection's
   * iterator.
   *

 *
 */
public interface Source {

    /**
     * Gets a byte stream to the source contents. Closing the returned stream is the responsibility of the caller.
     *
     * @return A byte stream to the source contents, never {@code null}.
     * @throws IOException in case of IO issue
     */
    InputStream getInputStream() throws IOException;

    /**