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