com.tngtech.archunit.core.domain.ThrowsDeclaration Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of archunit Show documentation
A Java architecture test library, to specify and assert architecture rules in plain Java - Module 'archunit'
There is a newer version: 1.3.0
/*
 * Copyright 2014-2024 TNG Technology Consulting GmbH
 *
 * 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.tngtech.archunit.core.domain;

import java.util.Objects;

import com.tngtech.archunit.PublicAPI;
import com.tngtech.archunit.base.ChainableFunction;
import com.tngtech.archunit.core.domain.AccessTarget.CodeUnitCallTarget;
import com.tngtech.archunit.core.domain.properties.CanBeAnnotated;
import com.tngtech.archunit.core.domain.properties.HasName;
import com.tngtech.archunit.core.domain.properties.HasOwner;
import com.tngtech.archunit.core.domain.properties.HasParameterTypes;
import com.tngtech.archunit.core.domain.properties.HasReturnType;
import com.tngtech.archunit.core.domain.properties.HasType;

import static com.tngtech.archunit.PublicAPI.Usage.ACCESS;

/**
 * Represents one declared exception of a {@link ThrowsClause}. I.e. for
 * void someMethod() throws FirstException, SecondException {...}
 * there would be one {@link ThrowsDeclaration} representing FirstException and one representing
 * SecondException
 *
 * @param  Represents the 'location' where this {@link ThrowsDeclaration} is declared. This can be a {@link JavaCodeUnit}, i.e.
 *                   a method or constructor. It can also be a {@link CodeUnitCallTarget CodeUnitCallTarget}
 *                   where the resolution process resolved this
 *                   {@link ThrowsDeclaration} on all resolved targets.

 *                   To further elaborate, suppose we have three interfaces

 *                   interface A { void method() throws E1, E2{...} }

 *                   interface B { void method() throws E2, E3{...} }

 *                   interface C extends A, B {}

 *                   Since C can be assigned to either A or B, it follows that
 *                   the inherited method C.method() only declares E2 as its only checked Exception.

 *                   Thus the {@link ThrowsClause} for the call target C.method() would only contain
 *                   a {@link ThrowsDeclaration} with type E2.

 *                   For further information about the resolution process of {@link AccessTarget AccessTargets} to
 *                   {@link JavaMember JavaMembers} consult the documentation at {@link AccessTarget}.
 */
@PublicAPI(usage = ACCESS)
public final class ThrowsDeclaration>
        implements HasType, HasOwner> {

    private final ThrowsClause throwsClause;
    private final JavaClass type;

    ThrowsDeclaration(ThrowsClause throwsClause, JavaClass type) {
        this.throwsClause = throwsClause;
        this.type = type;
    }

    /**
     * @return The {@link ThrowsClause} containing this declaration
     */
    @Override
    @PublicAPI(usage = ACCESS)
    public ThrowsClause getOwner() {
        return throwsClause;
    }

    @PublicAPI(usage = ACCESS)
    public ThrowsClause getThrowsClause() {
        return throwsClause;
    }

    /**
     * @return The 'location' where this {@link ThrowsDeclaration} is declared. Can be either {@link JavaCodeUnit}
     *         or {@link CodeUnitCallTarget}. Compare docs at {@link ThrowsDeclaration}.
     */
    @PublicAPI(usage = ACCESS)
    public LOCATION getLocation() {
        return throwsClause.getOwner();
    }

    /**
     * @return The class that declares the {@link LOCATION} (i.e. method, constructor, method call target, constructor call target)
     * containing this {@link ThrowsDeclaration}
     */
    @PublicAPI(usage = ACCESS)
    public JavaClass getDeclaringClass() {
        return getLocation().getOwner();
    }

    @Override
    @PublicAPI(usage = ACCESS)
    public JavaType getType() {
        return type;
    }

    /**
     * @return The type of this {@link ThrowsDeclaration}, e.g. for a method
     * void method() throws SomeException {...}
     * the {@link JavaClass} representing SomeException will be returned
     */
    @Override
    @PublicAPI(usage = ACCESS)
    public JavaClass getRawType() {
        return type;
    }

    @Override
    public int hashCode() {
        return Objects.hash(getLocation(), type);
    }

    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        if (obj == null || getClass() != obj.getClass()) {
            return false;
        }
        ThrowsDeclaration other = (ThrowsDeclaration) obj;
        return Objects.equals(this.getLocation(), other.getLocation())
                && Objects.equals(this.type, other.type);
    }

    @Override
    public String toString() {
        return getClass().getSimpleName() + "{location=" + getLocation() + ", type=" + type + '}';
    }

    /**
     * Predefined {@link ChainableFunction functions} to transform {@link ThrowsDeclaration}.
     * Note that due to inheritance further functions for {@link ThrowsDeclaration} can be found in the following locations:
     * 
     *     {@link HasType.Functions}
     *     {@link HasOwner.Functions}
     * 
     */
    @PublicAPI(usage = ACCESS)
    public static final class Functions {
        private Functions() {
        }

        @PublicAPI(usage = ACCESS)
        public static final class Get {
            private Get() {
            }

            @PublicAPI(usage = ACCESS)
            public static >
            ChainableFunction, T> location() {
                return new ChainableFunction, T>() {
                    @Override
                    public T apply(ThrowsDeclaration input) {
                        return input.getLocation();
                    }
                };
            }
        }
    }
}