1bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor/* 21d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copyright (C) 2007 The Guava Authors 3bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 4bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Licensed under the Apache License, Version 2.0 (the "License"); 5bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * you may not use this file except in compliance with the License. 6bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * You may obtain a copy of the License at 7bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 8bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * http://www.apache.org/licenses/LICENSE-2.0 9bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 10bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Unless required by applicable law or agreed to in writing, software 11bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * distributed under the License is distributed on an "AS IS" BASIS, 12bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * See the License for the specific language governing permissions and 14bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * limitations under the License. 15bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 16bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 17bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorpackage com.google.common.io; 18bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 19bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport static com.google.common.base.Preconditions.checkArgument; 20bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport static com.google.common.base.Preconditions.checkNotNull; 21bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 221d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.annotations.Beta; 231d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert 24bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport java.io.IOException; 25bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport java.io.InputStream; 26bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport java.io.InputStreamReader; 27bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport java.io.OutputStream; 28bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport java.net.URL; 29bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport java.nio.charset.Charset; 30bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorimport java.util.List; 31bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 32bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor/** 33bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Provides utility methods for working with resources in the classpath. 341d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Note that even though these methods use {@link URL} parameters, they 35bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * are usually not appropriate for HTTP or other non-classpath resources. 36bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 37bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * <p>All method parameters must be non-null unless documented otherwise. 38bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 39bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @author Chris Nokleberg 40bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @author Ben Yu 411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 1.0 42bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 431d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert@Beta 44bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnorpublic final class Resources { 451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert private Resources() {} 46bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 47bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 48bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Returns a factory that will supply instances of {@link InputStream} that 49bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * read from the given URL. 50bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 51bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param url the URL to read from 52bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return the factory 53bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 54bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static InputSupplier<InputStream> newInputStreamSupplier( 55bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor final URL url) { 56bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor checkNotNull(url); 57bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return new InputSupplier<InputStream>() { 581d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert @Override 59bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public InputStream getInput() throws IOException { 60bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return url.openStream(); 61bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 62bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor }; 63bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 64bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 65bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 66bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Returns a factory that will supply instances of 67bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * {@link InputStreamReader} that read a URL using the given character set. 68bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 69bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param url the URL to read from 70bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param charset the character set used when reading the URL contents 71bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return the factory 72bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 73bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static InputSupplier<InputStreamReader> newReaderSupplier( 74bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor URL url, Charset charset) { 75bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return CharStreams.newReaderSupplier(newInputStreamSupplier(url), charset); 76bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 77bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 78bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 79bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Reads all bytes from a URL into a byte array. 80bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 81bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param url the URL to read from 82bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return a byte array containing all the bytes from the URL 83bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @throws IOException if an I/O error occurs 84bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 85bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static byte[] toByteArray(URL url) throws IOException { 86bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return ByteStreams.toByteArray(newInputStreamSupplier(url)); 87bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 88bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 89bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 90bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Reads all characters from a URL into a {@link String}, using the given 91bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * character set. 92bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 93bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param url the URL to read from 94bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param charset the character set used when reading the URL 95bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return a string containing all the characters from the URL 96bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @throws IOException if an I/O error occurs. 97bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 98bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static String toString(URL url, Charset charset) throws IOException { 99bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return CharStreams.toString(newReaderSupplier(url, charset)); 100bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 101bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 102bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 103bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Streams lines from a URL, stopping when our callback returns false, or we 104bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * have read all of the lines. 105bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 106bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param url the URL to read from 107bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param charset the character set used when reading the URL 108bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param callback the LineProcessor to use to handle the lines 109bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return the output of processing the lines 110bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @throws IOException if an I/O error occurs 111bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 112bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static <T> T readLines(URL url, Charset charset, 113bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor LineProcessor<T> callback) throws IOException { 114bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return CharStreams.readLines(newReaderSupplier(url, charset), callback); 115bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 116bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 117bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 118bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Reads all of the lines from a URL. The lines do not include 119bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * line-termination characters, but do include other leading and trailing 120bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * whitespace. 121bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 122bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param url the URL to read from 123bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param charset the character set used when writing the file 124bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @return a mutable {@link List} containing all the lines 125bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @throws IOException if an I/O error occurs 126bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 127bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static List<String> readLines(URL url, Charset charset) 128bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor throws IOException { 129bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return CharStreams.readLines(newReaderSupplier(url, charset)); 130bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 131bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 132bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 133bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Copies all bytes from a URL to an output stream. 134bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 135bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param from the URL to read from 136bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @param to the output stream 137bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @throws IOException if an I/O error occurs 138bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 139bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static void copy(URL from, OutputStream to) throws IOException { 140bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor ByteStreams.copy(newInputStreamSupplier(from), to); 141bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 142bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 143bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 144bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Returns a {@code URL} pointing to {@code resourceName} if the resource is 145bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * found in the class path. {@code Resources.class.getClassLoader()} is used 146bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * to locate the resource. 147bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 148bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @throws IllegalArgumentException if resource is not found 149bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 150bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static URL getResource(String resourceName) { 151bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor URL url = Resources.class.getClassLoader().getResource(resourceName); 152bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor checkArgument(url != null, "resource %s not found.", resourceName); 153bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return url; 154bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 155bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor 156bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor /** 157bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * Returns a {@code URL} pointing to {@code resourceName} that is relative to 158bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * {@code contextClass}, if the resource is found in the class path. 159bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * 160bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor * @throws IllegalArgumentException if resource is not found 161bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor */ 162bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor public static URL getResource(Class<?> contextClass, String resourceName) { 163bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor URL url = contextClass.getResource(resourceName); 164bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor checkArgument(url != null, "resource %s relative to %s not found.", 165bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor resourceName, contextClass.getName()); 166bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor return url; 167bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor } 168bfe2dd089341dcb4c1fb65a5b6b077ad0ebbf6dcDan Egnor} 169