001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 005 * in compliance with the License. You may obtain a copy of the License at 006 * 007 * http://www.apache.org/licenses/LICENSE-2.0 008 * 009 * Unless required by applicable law or agreed to in writing, software distributed under the License 010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 011 * or implied. See the License for the specific language governing permissions and limitations under 012 * the License. 013 */ 014 015package com.google.common.io; 016 017import static com.google.common.base.Preconditions.checkArgument; 018import static com.google.common.base.Preconditions.checkNotNull; 019 020import com.google.common.annotations.Beta; 021import com.google.common.annotations.GwtIncompatible; 022import com.google.common.base.Charsets; 023import com.google.common.base.MoreObjects; 024import com.google.common.collect.Lists; 025import com.google.errorprone.annotations.CanIgnoreReturnValue; 026import java.io.IOException; 027import java.io.InputStream; 028import java.io.OutputStream; 029import java.net.URL; 030import java.nio.charset.Charset; 031import java.util.List; 032import org.checkerframework.checker.nullness.qual.Nullable; 033 034/** 035 * Provides utility methods for working with resources in the classpath. Note that even though these 036 * methods use {@link URL} parameters, they are usually not appropriate for HTTP or other 037 * non-classpath resources. 038 * 039 * <p>All method parameters must be non-null unless documented otherwise. 040 * 041 * @author Chris Nokleberg 042 * @author Ben Yu 043 * @author Colin Decker 044 * @since 1.0 045 */ 046@Beta 047@GwtIncompatible 048@ElementTypesAreNonnullByDefault 049public final class Resources { 050 private Resources() {} 051 052 /** 053 * Returns a {@link ByteSource} that reads from the given URL. 054 * 055 * @since 14.0 056 */ 057 public static ByteSource asByteSource(URL url) { 058 return new UrlByteSource(url); 059 } 060 061 /** A byte source that reads from a URL using {@link URL#openStream()}. */ 062 private static final class UrlByteSource extends ByteSource { 063 064 private final URL url; 065 066 private UrlByteSource(URL url) { 067 this.url = checkNotNull(url); 068 } 069 070 @Override 071 public InputStream openStream() throws IOException { 072 return url.openStream(); 073 } 074 075 @Override 076 public String toString() { 077 return "Resources.asByteSource(" + url + ")"; 078 } 079 } 080 081 /** 082 * Returns a {@link CharSource} that reads from the given URL using the given character set. 083 * 084 * @since 14.0 085 */ 086 public static CharSource asCharSource(URL url, Charset charset) { 087 return asByteSource(url).asCharSource(charset); 088 } 089 090 /** 091 * Reads all bytes from a URL into a byte array. 092 * 093 * @param url the URL to read from 094 * @return a byte array containing all the bytes from the URL 095 * @throws IOException if an I/O error occurs 096 */ 097 public static byte[] toByteArray(URL url) throws IOException { 098 return asByteSource(url).read(); 099 } 100 101 /** 102 * Reads all characters from a URL into a {@link String}, using the given character set. 103 * 104 * @param url the URL to read from 105 * @param charset the charset used to decode the input stream; see {@link Charsets} for helpful 106 * predefined constants 107 * @return a string containing all the characters from the URL 108 * @throws IOException if an I/O error occurs. 109 */ 110 public static String toString(URL url, Charset charset) throws IOException { 111 return asCharSource(url, charset).read(); 112 } 113 114 /** 115 * Streams lines from a URL, stopping when our callback returns false, or we have read all of the 116 * lines. 117 * 118 * @param url the URL to read from 119 * @param charset the charset used to decode the input stream; see {@link Charsets} for helpful 120 * predefined constants 121 * @param callback the LineProcessor to use to handle the lines 122 * @return the output of processing the lines 123 * @throws IOException if an I/O error occurs 124 */ 125 @CanIgnoreReturnValue // some processors won't return a useful result 126 @ParametricNullness 127 public static <T extends @Nullable Object> T readLines( 128 URL url, Charset charset, LineProcessor<T> callback) throws IOException { 129 return asCharSource(url, charset).readLines(callback); 130 } 131 132 /** 133 * Reads all of the lines from a URL. The lines do not include line-termination characters, but do 134 * include other leading and trailing whitespace. 135 * 136 * <p>This method returns a mutable {@code List}. For an {@code ImmutableList}, use {@code 137 * Resources.asCharSource(url, charset).readLines()}. 138 * 139 * @param url the URL to read from 140 * @param charset the charset used to decode the input stream; see {@link Charsets} for helpful 141 * predefined constants 142 * @return a mutable {@link List} containing all the lines 143 * @throws IOException if an I/O error occurs 144 */ 145 public static List<String> readLines(URL url, Charset charset) throws IOException { 146 // don't use asCharSource(url, charset).readLines() because that returns 147 // an immutable list, which would change the behavior of this method 148 return readLines( 149 url, 150 charset, 151 new LineProcessor<List<String>>() { 152 final List<String> result = Lists.newArrayList(); 153 154 @Override 155 public boolean processLine(String line) { 156 result.add(line); 157 return true; 158 } 159 160 @Override 161 public List<String> getResult() { 162 return result; 163 } 164 }); 165 } 166 167 /** 168 * Copies all bytes from a URL to an output stream. 169 * 170 * @param from the URL to read from 171 * @param to the output stream 172 * @throws IOException if an I/O error occurs 173 */ 174 public static void copy(URL from, OutputStream to) throws IOException { 175 asByteSource(from).copyTo(to); 176 } 177 178 /** 179 * Returns a {@code URL} pointing to {@code resourceName} if the resource is found using the 180 * {@linkplain Thread#getContextClassLoader() context class loader}. In simple environments, the 181 * context class loader will find resources from the class path. In environments where different 182 * threads can have different class loaders, for example app servers, the context class loader 183 * will typically have been set to an appropriate loader for the current thread. 184 * 185 * <p>In the unusual case where the context class loader is null, the class loader that loaded 186 * this class ({@code Resources}) will be used instead. 187 * 188 * @throws IllegalArgumentException if the resource is not found 189 */ 190 @CanIgnoreReturnValue // being used to check if a resource exists 191 // TODO(cgdecker): maybe add a better way to check if a resource exists 192 // e.g. Optional<URL> tryGetResource or boolean resourceExists 193 public static URL getResource(String resourceName) { 194 ClassLoader loader = 195 MoreObjects.firstNonNull( 196 Thread.currentThread().getContextClassLoader(), Resources.class.getClassLoader()); 197 URL url = loader.getResource(resourceName); 198 checkArgument(url != null, "resource %s not found.", resourceName); 199 return url; 200 } 201 202 /** 203 * Given a {@code resourceName} that is relative to {@code contextClass}, returns a {@code URL} 204 * pointing to the named resource. 205 * 206 * @throws IllegalArgumentException if the resource is not found 207 */ 208 @CanIgnoreReturnValue // being used to check if a resource exists 209 public static URL getResource(Class<?> contextClass, String resourceName) { 210 URL url = contextClass.getResource(resourceName); 211 checkArgument( 212 url != null, "resource %s relative to %s not found.", resourceName, contextClass.getName()); 213 return url; 214 } 215}