All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.base.Throwables Maven / Gradle / Ivy

Go to download

Guava is a suite of core and expanded libraries that include utility classes, google's collections, io classes, and much much more.

There is a newer version: 33.3.0-jre
Show newest version
/*
 * Copyright (C) 2007 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.base;

import static com.google.common.base.Preconditions.checkNotNull;

import com.google.common.annotations.Beta;

import java.io.PrintWriter;
import java.io.StringWriter;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import javax.annotation.Nullable;

/**
 * Static utility methods pertaining to instances of {@link Throwable}.
 *
 * 

See the Guava User Guide entry on * Throwables. * * @author Kevin Bourrillion * @author Ben Yu * @since 1.0 */ public final class Throwables { private Throwables() {} /** * Propagates {@code throwable} exactly as-is, if and only if it is an * instance of {@code declaredType}. Example usage: *

   *   try {
   *     someMethodThatCouldThrowAnything();
   *   } catch (IKnowWhatToDoWithThisException e) {
   *     handle(e);
   *   } catch (Throwable t) {
   *     Throwables.propagateIfInstanceOf(t, IOException.class);
   *     Throwables.propagateIfInstanceOf(t, SQLException.class);
   *     throw Throwables.propagate(t);
   *   }
   * 
*/ public static void propagateIfInstanceOf( @Nullable Throwable throwable, Class declaredType) throws X { // Check for null is needed to avoid frequent JNI calls to isInstance(). if (throwable != null && declaredType.isInstance(throwable)) { throw declaredType.cast(throwable); } } /** * Propagates {@code throwable} exactly as-is, if and only if it is an * instance of {@link RuntimeException} or {@link Error}. Example usage: *
   *   try {
   *     someMethodThatCouldThrowAnything();
   *   } catch (IKnowWhatToDoWithThisException e) {
   *     handle(e);
   *   } catch (Throwable t) {
   *     Throwables.propagateIfPossible(t);
   *     throw new RuntimeException("unexpected", t);
   *   }
   * 
*/ public static void propagateIfPossible(@Nullable Throwable throwable) { propagateIfInstanceOf(throwable, Error.class); propagateIfInstanceOf(throwable, RuntimeException.class); } /** * Propagates {@code throwable} exactly as-is, if and only if it is an * instance of {@link RuntimeException}, {@link Error}, or * {@code declaredType}. Example usage: *
   *   try {
   *     someMethodThatCouldThrowAnything();
   *   } catch (IKnowWhatToDoWithThisException e) {
   *     handle(e);
   *   } catch (Throwable t) {
   *     Throwables.propagateIfPossible(t, OtherException.class);
   *     throw new RuntimeException("unexpected", t);
   *   }
   * 
* * @param throwable the Throwable to possibly propagate * @param declaredType the single checked exception type declared by the * calling method */ public static void propagateIfPossible( @Nullable Throwable throwable, Class declaredType) throws X { propagateIfInstanceOf(throwable, declaredType); propagateIfPossible(throwable); } /** * Propagates {@code throwable} exactly as-is, if and only if it is an * instance of {@link RuntimeException}, {@link Error}, {@code declaredType1}, * or {@code declaredType2}. In the unlikely case that you have three or more * declared checked exception types, you can handle them all by invoking these * methods repeatedly. See usage example in {@link * #propagateIfPossible(Throwable, Class)}. * * @param throwable the Throwable to possibly propagate * @param declaredType1 any checked exception type declared by the calling * method * @param declaredType2 any other checked exception type declared by the * calling method */ public static void propagateIfPossible(@Nullable Throwable throwable, Class declaredType1, Class declaredType2) throws X1, X2 { checkNotNull(declaredType2); propagateIfInstanceOf(throwable, declaredType1); propagateIfPossible(throwable, declaredType2); } /** * Propagates {@code throwable} as-is if it is an instance of * {@link RuntimeException} or {@link Error}, or else as a last resort, wraps * it in a {@code RuntimeException} then propagates. *

* This method always throws an exception. The {@code RuntimeException} return * type is only for client code to make Java type system happy in case a * return value is required by the enclosing method. Example usage: *

   *   T doSomething() {
   *     try {
   *       return someMethodThatCouldThrowAnything();
   *     } catch (IKnowWhatToDoWithThisException e) {
   *       return handle(e);
   *     } catch (Throwable t) {
   *       throw Throwables.propagate(t);
   *     }
   *   }
   * 
* * @param throwable the Throwable to propagate * @return nothing will ever be returned; this return type is only for your * convenience, as illustrated in the example above */ public static RuntimeException propagate(Throwable throwable) { propagateIfPossible(checkNotNull(throwable)); throw new RuntimeException(throwable); } /** * Returns the innermost cause of {@code throwable}. The first throwable in a * chain provides context from when the error or exception was initially * detected. Example usage: *
   *   assertEquals("Unable to assign a customer id",
   *       Throwables.getRootCause(e).getMessage());
   * 
*/ public static Throwable getRootCause(Throwable throwable) { Throwable cause; while ((cause = throwable.getCause()) != null) { throwable = cause; } return throwable; } /** * Gets a {@code Throwable} cause chain as a list. The first entry in the * list will be {@code throwable} followed by its cause hierarchy. Note * that this is a snapshot of the cause chain and will not reflect * any subsequent changes to the cause chain. * *

Here's an example of how it can be used to find specific types * of exceptions in the cause chain: * *

   * Iterables.filter(Throwables.getCausalChain(e), IOException.class));
   * 
* * @param throwable the non-null {@code Throwable} to extract causes from * @return an unmodifiable list containing the cause chain starting with * {@code throwable} */ @Beta // TODO(kevinb): decide best return type public static List getCausalChain(Throwable throwable) { checkNotNull(throwable); List causes = new ArrayList(4); while (throwable != null) { causes.add(throwable); throwable = throwable.getCause(); } return Collections.unmodifiableList(causes); } /** * Returns a string containing the result of * {@link Throwable#toString() toString()}, followed by the full, recursive * stack trace of {@code throwable}. Note that you probably should not be * parsing the resulting string; if you need programmatic access to the stack * frames, you can call {@link Throwable#getStackTrace()}. */ public static String getStackTraceAsString(Throwable throwable) { StringWriter stringWriter = new StringWriter(); throwable.printStackTrace(new PrintWriter(stringWriter)); return stringWriter.toString(); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy