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
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    }