Java example source code file (ClusterException.java)

This example Java source code file (ClusterException.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

arraylist, can't, clusterexception, collection, exceptioncollection, gwtcompatible, illegalargumentexception, runtimeexception, the, throwable, util

The ClusterException.java Java example source code

/*
 * Copyright (C) 2009 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.testing;

import com.google.common.annotations.GwtCompatible;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;

/**
 * An {@link ClusterException} is a data structure that allows for some code to
 * "throw multiple exceptions", or something close to it. The prototypical code
 * that calls for this class is presented below:
 *
 * <pre>
 * void runManyThings(List<ThingToRun> thingsToRun) {
 *   for (ThingToRun thingToRun : thingsToRun) {
 *     thingToRun.run(); // <-- say this may throw an exception, but you want to
 *                       // always run all thingsToRun
 *   }
 * }
 * </pre>
 *
 * <p>This is what the code would become:
 *
 * <pre>
 * void runManyThings(List<ThingToRun> thingsToRun) {
 *   List<Exception> exceptions = Lists.newArrayList();
 *   for (ThingToRun thingToRun : thingsToRun) {
 *     try {
 *       thingToRun.run();
 *     } catch (Exception e) {
 *       exceptions.add(e);
 *     }
 *   }
 *   if (exceptions.size() > 0) {
 *     throw ClusterException.create(exceptions);
 *   }
 * }
 * </pre>
 *
 * <p>See semantic details at {@link #create(Collection)}.
 *
 * @author Luiz-Otavio Zorzella
 */
@GwtCompatible
final class ClusterException extends RuntimeException {

  public final Collection<? extends Throwable> exceptions;

  private ClusterException(Collection<? extends Throwable> exceptions) {
    super(
        exceptions.size() + " exceptions were thrown. The first exception is listed as a cause.",
        exceptions.iterator().next());
    ArrayList<Throwable> temp = new ArrayList();
    temp.addAll(exceptions);
    this.exceptions = Collections.unmodifiableCollection(temp);
  }

  /**
   * @see #create(Collection)
   */
  public static RuntimeException create(Throwable... exceptions) {
    ArrayList<Throwable> temp = new ArrayList();
    for (Throwable exception : exceptions) {
      temp.add(exception);
    }
    return create(temp);
  }

  /**
   * Given a collection of exceptions, returns a {@link RuntimeException}, with
   * the following rules:
   *
   * <ul>
   *  <li>If {@code exceptions} has a single exception and that exception is a
   *    {@link RuntimeException}, return it
   *  <li>If {@code exceptions} has a single exceptions and that exceptions is
   *    <em>not a {@link RuntimeException}, return a simple
   *    {@code RuntimeException} that wraps it
   *  <li>Otherwise, return an instance of {@link ClusterException} that wraps
   *    the first exception in the {@code exceptions} collection.
   * </ul>
   *
   * <p>Though this method takes any {@link Collection}, it often makes most
   * sense to pass a {@link java.util.List} or some other collection that
   * preserves the order in which the exceptions got added.
   *
   * @throws NullPointerException if {@code exceptions} is null
   * @throws IllegalArgumentException if {@code exceptions} is empty
   */
  public static RuntimeException create(Collection<? extends Throwable> exceptions) {
    if (exceptions.size() == 0) {
      throw new IllegalArgumentException(
          "Can't create an ExceptionCollection with no exceptions");
    }
    if (exceptions.size() == 1) {
      Throwable temp = exceptions.iterator().next();
      if (temp instanceof RuntimeException) {
        return (RuntimeException)temp;
      } else {
        return new RuntimeException(temp);
      }
    }
    return new ClusterException(exceptions);
  }
}