/*
 * Copyright 2017, TeamDev Ltd. All rights reserved.
 *
 * Redistribution and use in source and/or binary forms, with or without
 * modification, must retain the above copyright notice and the following
 * disclaimer.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package org.spine3.util;

import com.google.common.base.Throwables;
import org.spine3.validate.ConversionError;
import org.spine3.validate.IllegalConversionArgumentException;

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

/**
 * Utility class for working with exceptions for cases that are not
 * supported by {@link com.google.common.base.Throwables Throwables}.
 *
 * @author Alexander Yevsyukov
 */
public class Exceptions {

    private Exceptions() {}

    /**
     * Always throws {@code UnsupportedOperationException} initialized with the passed string.
     *
     * <p>Use this method in combination with static import for brevity of code for
     * unsupported operations.
     * The return type is given to keep Java type system happy when called in methods with
     * return type as shown below:
     *
     * <pre>
     *   import static com.teamdev.commons.Exceptions.unsupported;
     *   ...
     *   T doSomething() {
     *      throw unsupported("Cannot do this");
     *   }
     * </pre>
     *
     * @param message a message for exception
     * @return nothing ever
     * @throws UnsupportedOperationException always
     */
    public static UnsupportedOperationException unsupported(String message)
            throws UnsupportedOperationException {
        checkNotNull(message);
        throw new UnsupportedOperationException(message);
    }

    /**
     * Always throws {@code UnsupportedOperationException}.
     *
     * <p>Use this method in combination with static import for brevity of code for
     * unsupported operations.
     * The return type is given to keep Java type system happy when called in methods with
     * return type as shown below:
     *
     * <pre>
     *   import static com.teamdev.commons.Exceptions.unsupported;
     *   ...
     *   T doSomething() {
     *      throw unsupported();
     *   }
     * </pre>
     *
     * @return nothing ever
     * @throws UnsupportedOperationException always
     */
    @SuppressWarnings("NewExceptionWithoutArguments") // No message necessary for this case.
    public static UnsupportedOperationException unsupported() throws UnsupportedOperationException {
        throw new UnsupportedOperationException();
    }

    /**
     * Sets a throwable's cause as the cause of a {@link IllegalStateException} and throws it.
     *
     * @param throwable to wrap
     * @return always throws an exception, the return type is for convenience
     */
    public static IllegalStateException wrappedCause(Throwable throwable) {
        checkNotNull(throwable);
        final Throwable cause = Throwables.getRootCause(throwable);
        throw new IllegalStateException(cause);
    }

    /**
     * Always throws {@code UnsupportedOperationException}.
     *
     * <p>Use this method in combination with static import for brevity of code for
     * unsupported operations.
     * The return type is given to keep Java type system happy when called in methods with
     * return type as shown below:
     *
     * <pre>
     *   import static com.teamdev.commons.Exceptions.unsupported;
     *   ...
     *   T doSomething() {
     *      throw unsupported();
     *   }
     * </pre>
     *
     * @param exMessage a message for exception
     * @return nothing ever
     * @throws UnsupportedOperationException always
     */
    public static IllegalConversionArgumentException conversionArgumentException(String exMessage) {
        throw new IllegalConversionArgumentException(new ConversionError(exMessage));
    }
}

@@ -3731,49 +3731,48 @@
   * 
-Always throws %7B@code UnsupportedOperation
+Creates %7B@link IllegalConversionArgument
 Exce
@@ -3781,561 +3781,237 @@
 ion%7D
-.
 %0A     *
-%0A     * %3Cp%3EUse this method in combination with static import for brevity of code for%0A     * unsupported operations.%0A     * The return type is given to keep Java type system happy when called in methods with%0A     * return type as shown below:%0A     *%0A     * %3Cpre%3E%0A     *   import static com.teamdev.commons.Exceptions.unsupported;%0A     *   ...%0A     *   T doSomething() %7B%0A     *      throw unsupported();%0A     *   %7D%0A     * %3C/pre%3E%0A     *%0A     * @param exMessage a message for exception%0A     * @return nothing ever%0A     * @throws UnsupportedOperation
+ with specified exception message and throws it.%0A     *%0A     * @param exMessage a message for exception%0A     * @return always throws an exception, the return type is for convenience%0A     * @throws IllegalConversionArgument
 Exce

Fix the documentation.