EaglerForge/sources/main/java/com/google/common/base/Throwables.java

/*
 * 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 java.io.PrintWriter;
import java.io.StringWriter;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import javax.annotation.Nullable;

import com.google.common.annotations.Beta;

import net.lax1dude.eaglercraft.v1_8.EagRuntime;

/**
 * Static utility methods pertaining to instances of {@link Throwable}.
 *
 * <p>
 * See the Guava User Guide entry on
 * <a href= "http://code.google.com/p/guava-libraries/wiki/ThrowablesExplained">
 * Throwables</a>.
 *
 * @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:
	 * 
	 * <pre>
	 * try {
	 * 	someMethodThatCouldThrowAnything();
	 * } catch (IKnowWhatToDoWithThisException e) {
	 * 	handle(e);
	 * } catch (Throwable t) {
	 * 	Throwables.propagateIfInstanceOf(t, IOException.class);
	 * 	Throwables.propagateIfInstanceOf(t, SQLException.class);
	 * 	throw Throwables.propagate(t);
	 * }
	 * </pre>
	 */
	public static <X extends Throwable> void propagateIfInstanceOf(@Nullable Throwable throwable, Class<X> 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:
	 * 
	 * <pre>
	 * try {
	 * 	someMethodThatCouldThrowAnything();
	 * } catch (IKnowWhatToDoWithThisException e) {
	 * 	handle(e);
	 * } catch (Throwable t) {
	 * 	Throwables.propagateIfPossible(t);
	 * 	throw new RuntimeException("unexpected", t);
	 * }
	 * </pre>
	 */
	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:
	 * 
	 * <pre>
	 * try {
	 * 	someMethodThatCouldThrowAnything();
	 * } catch (IKnowWhatToDoWithThisException e) {
	 * 	handle(e);
	 * } catch (Throwable t) {
	 * 	Throwables.propagateIfPossible(t, OtherException.class);
	 * 	throw new RuntimeException("unexpected", t);
	 * }
	 * </pre>
	 *
	 * @param throwable    the Throwable to possibly propagate
	 * @param declaredType the single checked exception type declared by the calling
	 *                     method
	 */
	public static <X extends Throwable> void propagateIfPossible(@Nullable Throwable throwable, Class<X> 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 <X1 extends Throwable, X2 extends Throwable> void propagateIfPossible(@Nullable Throwable throwable,
			Class<X1> declaredType1, Class<X2> 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.
	 * <p>
	 * 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:
	 * 
	 * <pre>
	 * T doSomething() {
	 * 	try {
	 * 		return someMethodThatCouldThrowAnything();
	 * 	} catch (IKnowWhatToDoWithThisException e) {
	 * 		return handle(e);
	 * 	} catch (Throwable t) {
	 * 		throw Throwables.propagate(t);
	 * 	}
	 * }
	 * </pre>
	 *
	 * @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:
	 * 
	 * <pre>
	 * assertEquals("Unable to assign a customer id", Throwables.getRootCause(e).getMessage());
	 * </pre>
	 */
	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.
	 *
	 * <p>
	 * Here's an example of how it can be used to find specific types of exceptions
	 * in the cause chain:
	 *
	 * <pre>
	 * Iterables.filter(Throwables.getCausalChain(e), IOException.class));
	 * </pre>
	 *
	 * @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<Throwable> getCausalChain(Throwable throwable) {
		checkNotNull(throwable);
		List<Throwable> causes = new ArrayList<Throwable>(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) {
		return EagRuntime.getStackTrace(throwable);
	}
}