1/* 2 * Copyright (C) 2007 The Guava Authors 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 17package com.google.common.io; 18 19import static com.google.common.base.Preconditions.checkArgument; 20import static com.google.common.base.Preconditions.checkNotNull; 21 22import com.google.common.annotations.Beta; 23 24import java.io.IOException; 25import java.io.InputStream; 26import java.io.InputStreamReader; 27import java.io.OutputStream; 28import java.net.URL; 29import java.nio.charset.Charset; 30import java.util.List; 31 32/** 33 * Provides utility methods for working with resources in the classpath. 34 * Note that even though these methods use {@link URL} parameters, they 35 * are usually not appropriate for HTTP or other non-classpath resources. 36 * 37 * <p>All method parameters must be non-null unless documented otherwise. 38 * 39 * @author Chris Nokleberg 40 * @author Ben Yu 41 * @since 1.0 42 */ 43@Beta 44public final class Resources { 45 private Resources() {} 46 47 /** 48 * Returns a factory that will supply instances of {@link InputStream} that 49 * read from the given URL. 50 * 51 * @param url the URL to read from 52 * @return the factory 53 */ 54 public static InputSupplier<InputStream> newInputStreamSupplier( 55 final URL url) { 56 checkNotNull(url); 57 return new InputSupplier<InputStream>() { 58 @Override 59 public InputStream getInput() throws IOException { 60 return url.openStream(); 61 } 62 }; 63 } 64 65 /** 66 * Returns a factory that will supply instances of 67 * {@link InputStreamReader} that read a URL using the given character set. 68 * 69 * @param url the URL to read from 70 * @param charset the character set used when reading the URL contents 71 * @return the factory 72 */ 73 public static InputSupplier<InputStreamReader> newReaderSupplier( 74 URL url, Charset charset) { 75 return CharStreams.newReaderSupplier(newInputStreamSupplier(url), charset); 76 } 77 78 /** 79 * Reads all bytes from a URL into a byte array. 80 * 81 * @param url the URL to read from 82 * @return a byte array containing all the bytes from the URL 83 * @throws IOException if an I/O error occurs 84 */ 85 public static byte[] toByteArray(URL url) throws IOException { 86 return ByteStreams.toByteArray(newInputStreamSupplier(url)); 87 } 88 89 /** 90 * Reads all characters from a URL into a {@link String}, using the given 91 * character set. 92 * 93 * @param url the URL to read from 94 * @param charset the character set used when reading the URL 95 * @return a string containing all the characters from the URL 96 * @throws IOException if an I/O error occurs. 97 */ 98 public static String toString(URL url, Charset charset) throws IOException { 99 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} 169