    001    /*
    002     * Copyright (C) 2007 The Guava Authors
    003     *
    004     * Licensed under the Apache License, Version 2.0 (the "License");
    005     * you may not use this file except in compliance with the License.
    006     * You may obtain a copy of the License at
    007     *
    008     * http://www.apache.org/licenses/LICENSE-2.0
    009     *
    010     * Unless required by applicable law or agreed to in writing, software
    011     * distributed under the License is distributed on an "AS IS" BASIS,
    012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    013     * See the License for the specific language governing permissions and
    014     * limitations under the License.
    015     */
    016
    017    package com.google.common.io;
    018
    019    import static com.google.common.base.Preconditions.checkArgument;
    020    import static com.google.common.base.Preconditions.checkNotNull;
    021
    022    import com.google.common.annotations.Beta;
    023
    024    import java.io.IOException;
    025    import java.io.InputStream;
    026    import java.io.InputStreamReader;
    027    import java.io.OutputStream;
    028    import java.net.URL;
    029    import java.nio.charset.Charset;
    030    import java.util.List;
    031
    032    /**
    033     * Provides utility methods for working with resources in the classpath.
    034     * Note that even though these methods use {@link URL} parameters, they
    035     * are usually not appropriate for HTTP or other non-classpath resources.
    036     *
    037     * <p>All method parameters must be non-null unless documented otherwise.
    038     *
    039     * @author Chris Nokleberg
    040     * @author Ben Yu
    041     * @since 1.0
    042     */
    043    @Beta
    044    public final class Resources {
    045      private Resources() {}
    046
    047      /**
    048       * Returns a factory that will supply instances of {@link InputStream} that
    049       * read from the given URL.
    050       *
    051       * @param url the URL to read from
    052       * @return the factory
    053       */
    054      public static InputSupplier<InputStream> newInputStreamSupplier(
    055          final URL url) {
    056        checkNotNull(url);
    057        return new InputSupplier<InputStream>() {
    058          @Override
    059          public InputStream getInput() throws IOException {
    060            return url.openStream();
    061          }
    062        };
    063      }
    064
    065      /**
    066       * Returns a factory that will supply instances of
    067       * {@link InputStreamReader} that read a URL using the given character set.
    068       *
    069       * @param url the URL to read from
    070       * @param charset the character set used when reading the URL contents
    071       * @return the factory
    072       */
    073      public static InputSupplier<InputStreamReader> newReaderSupplier(
    074          URL url, Charset charset) {
    075        return CharStreams.newReaderSupplier(newInputStreamSupplier(url), charset);
    076      }
    077
    078      /**
    079       * Reads all bytes from a URL into a byte array.
    080       *
    081       * @param url the URL to read from
    082       * @return a byte array containing all the bytes from the URL
    083       * @throws IOException if an I/O error occurs
    084       */
    085      public static byte[] toByteArray(URL url) throws IOException {
    086        return ByteStreams.toByteArray(newInputStreamSupplier(url));
    087      }
    088
    089      /**
    090       * Reads all characters from a URL into a {@link String}, using the given
    091       * character set.
    092       *
    093       * @param url the URL to read from
    094       * @param charset the character set used when reading the URL
    095       * @return a string containing all the characters from the URL
    096       * @throws IOException if an I/O error occurs.
    097       */
    098      public static String toString(URL url, Charset charset) throws IOException {
    099        return CharStreams.toString(newReaderSupplier(url, charset));
    100      }
    101
    102      /**
    103       * Streams lines from a URL, stopping when our callback returns false, or we
    104       * have read all of the lines.
    105       *
    106       * @param url the URL to read from
    107       * @param charset the character set used when reading the URL
    108       * @param callback the LineProcessor to use to handle the lines
    109       * @return the output of processing the lines
    110       * @throws IOException if an I/O error occurs
    111       */
    112      public static <T> T readLines(URL url, Charset charset,
    113          LineProcessor<T> callback) throws IOException {
    114        return CharStreams.readLines(newReaderSupplier(url, charset), callback);
    115      }
    116
    117      /**
    118       * Reads all of the lines from a URL. The lines do not include
    119       * line-termination characters, but do include other leading and trailing
    120       * whitespace.
    121       *
    122       * @param url the URL to read from
    123       * @param charset the character set used when writing the file
    124       * @return a mutable {@link List} containing all the lines
    125       * @throws IOException if an I/O error occurs
    126       */
    127      public static List<String> readLines(URL url, Charset charset)
    128          throws IOException {
    129        return CharStreams.readLines(newReaderSupplier(url, charset));
    130      }
    131
    132      /**
    133       * Copies all bytes from a URL to an output stream.
    134       *
    135       * @param from the URL to read from
    136       * @param to the output stream
    137       * @throws IOException if an I/O error occurs
    138       */
    139      public static void copy(URL from, OutputStream to) throws IOException {
    140        ByteStreams.copy(newInputStreamSupplier(from), to);
    141      }
    142
    143      /**
    144       * Returns a {@code URL} pointing to {@code resourceName} if the resource is
    145       * found in the class path. {@code Resources.class.getClassLoader()} is used
    146       * to locate the resource.
    147       *
    148       * @throws IllegalArgumentException if resource is not found
    149       */
    150      public static URL getResource(String resourceName) {
    151        URL url = Resources.class.getClassLoader().getResource(resourceName);
    152        checkArgument(url != null, "resource %s not found.", resourceName);
    153        return url;
    154      }
    155
    156      /**
    157       * Returns a {@code URL} pointing to {@code resourceName} that is relative to
    158       * {@code contextClass}, if the resource is found in the class path.
    159       *
    160       * @throws IllegalArgumentException if resource is not found
    161       */
    162      public static URL getResource(Class<?> contextClass, String resourceName) {
    163        URL url = contextClass.getResource(resourceName);
    164        checkArgument(url != null, "resource %s relative to %s not found.",
    165            resourceName, contextClass.getName());
    166        return url;
    167      }
    168    }