Resources
Date: 2016-05-24

com.google.common.io

## Class Resources

- java.lang.Object
- - com.google.common.io.Resources

-     @Beta
      public final class Resources
      extends java.lang.Object

  Provides utility methods for working with resources in the classpath. Note that even though these methods use `URL` parameters, they are usually not appropriate for HTTP or other non-classpath resources.

  All method parameters must be non-null unless documented otherwise.

  Since:
    1.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ByteSource` | `asByteSource(java.net.URL url)` Returns a `ByteSource` that reads from the given URL.
    `static CharSource` | `asCharSource(java.net.URL url, java.nio.charset.Charset charset)` Returns a `CharSource` that reads from the given URL using the given character set.
    `static void` | `copy(java.net.URL from, java.io.OutputStream to)` Copies all bytes from a URL to an output stream.
    `static java.net.URL` | `getResource(java.lang.Class<?> contextClass, java.lang.String resourceName)` Given a `resourceName` that is relative to `contextClass`, returns a `URL` pointing to the named resource.
    `static java.net.URL` | `getResource(java.lang.String resourceName)` Returns a `URL` pointing to `resourceName` if the resource is found using the context class loader.
    `static java.util.List<java.lang.String>` | `readLines(java.net.URL url, java.nio.charset.Charset charset)` Reads all of the lines from a URL.
    `static <T> T` | `readLines(java.net.URL url, java.nio.charset.Charset charset, LineProcessor<T> callback)` Streams lines from a URL, stopping when our callback returns false, or we have read all of the lines.
    `static byte[]` | `toByteArray(java.net.URL url)` Reads all bytes from a URL into a byte array.
    `static java.lang.String` | `toString(java.net.URL url, java.nio.charset.Charset charset)` Reads all characters from a URL into a `String`, using the given character set.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### asByteSource

          public static ByteSource asByteSource(java.net.URL url)

      Returns a `ByteSource` that reads from the given URL.
      Since:
        14.0

    - #### asCharSource

          public static CharSource asCharSource(java.net.URL url,
                                java.nio.charset.Charset charset)

      Returns a `CharSource` that reads from the given URL using the given character set.
      Since:
        14.0

    - #### toByteArray

          public static byte[] toByteArray(java.net.URL url)
                                    throws java.io.IOException

      Reads all bytes from a URL into a byte array.
      Parameters:
        `url` - the URL to read from
      Returns:
        a byte array containing all the bytes from the URL
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### toString

          public static java.lang.String toString(java.net.URL url,
                                  java.nio.charset.Charset charset)
                                           throws java.io.IOException

      Reads all characters from a URL into a `String`, using the given character set.
      Parameters:
        `url` - the URL to read from
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
      Returns:
        a string containing all the characters from the URL
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### readLines

          public static <T> T readLines(java.net.URL url,
                        java.nio.charset.Charset charset,
                        LineProcessor<T> callback)
                             throws java.io.IOException

      Streams lines from a URL, stopping when our callback returns false, or we have read all of the lines.
      Parameters:
        `url` - the URL to read from
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
        `callback` - the LineProcessor to use to handle the lines
      Returns:
        the output of processing the lines
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readLines

          public static java.util.List<java.lang.String> readLines(java.net.URL url,
                                                   java.nio.charset.Charset charset)
                                                            throws java.io.IOException

      Reads all of the lines from a URL. The lines do not include line-termination characters, but do include other leading and trailing whitespace.

      This method returns a mutable `List`. For an `ImmutableList`, use `Resources.asCharSource(url, charset).readLines()`.

      Parameters:
        `url` - the URL to read from
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
      Returns:
        a mutable `List` containing all the lines
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### copy

          public static void copy(java.net.URL from,
                  java.io.OutputStream to)
                           throws java.io.IOException

      Copies all bytes from a URL to an output stream.
      Parameters:
        `from` - the URL to read from
        `to` - the output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### getResource

          public static java.net.URL getResource(java.lang.String resourceName)

      Returns a `URL` pointing to `resourceName` if the resource is found using the context class loader. In simple environments, the context class loader will find resources from the class path. In environments where different threads can have different class loaders, for example app servers, the context class loader will typically have been set to an appropriate loader for the current thread.

      In the unusual case where the context class loader is null, the class loader that loaded this class (`Resources`) will be used instead.

      Throws:
        `java.lang.IllegalArgumentException` - if the resource is not found

    - #### getResource

          public static java.net.URL getResource(java.lang.Class<?> contextClass,
                                 java.lang.String resourceName)

      Given a `resourceName` that is relative to `contextClass`, returns a `URL` pointing to the named resource.
      Throws:
        `java.lang.IllegalArgumentException` - if the resource is not found