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

graphql.GraphQLError Maven / Gradle / Ivy

There is a newer version: 230521-nf-execution
Show newest version
package graphql;


import graphql.execution.ResultPath;
import graphql.language.SourceLocation;
import org.jetbrains.annotations.Nullable;

import java.io.Serializable;
import java.util.List;
import java.util.Map;

/**
 * The interface describing graphql errors
 *
 * NOTE: This class implements {@link java.io.Serializable} and hence it can be serialised and placed into a distributed cache.  However we
 * are not aiming to provide long term compatibility and do not intend for you to place this serialised data into permanent storage,
 * with times frames that cross graphql-java versions.  While we don't change things unnecessarily,  we may inadvertently break
 * the serialised compatibility across versions.
 *
 * @see GraphQL Spec - 7.1.2 Errors
 */
@PublicApi
public interface GraphQLError extends Serializable {

    /**
     * @return a description of the error intended for the developer as a guide to understand and correct the error
     */
    String getMessage();

    /**
     * @return the location(s) within the GraphQL document at which the error occurred. Each {@link SourceLocation}
     * describes the beginning of an associated syntax element
     */
    List getLocations();

    /**
     * @return an object classifying this error
     */
    ErrorClassification getErrorType();

    /**
     * The graphql spec says that the (optional) path field of any error must be
     * a list of path entries starting at the root of the response
     * and ending with the field associated with the error
     * https://spec.graphql.org/draft/#sec-Errors.Error-Result-Format
     *
     * @return the path in list format
     */
    default List getPath() {
        return null;
    }

    /**
     * The graphql specification says that result of a call should be a map that follows certain rules on what items
     * should be present.  Certain JSON serializers may or may interpret the error to spec, so this method
     * is provided to produce a map that strictly follows the specification.
     *
     * See : GraphQL Spec - 7.1.2 Errors
     *
     * @return a map of the error that strictly follows the specification
     */
    default Map toSpecification() {
        return GraphqlErrorHelper.toSpecification(this);
    }

    /**
     * @return a map of error extensions or null if there are none
     */
    default Map getExtensions() {
        return null;
    }

    /**
     * @return a new builder of {@link GraphQLError}s
     */
    static Builder newError() {
        return new GraphqlErrorBuilder<>();
    }

    /**
     * A builder of {@link GraphQLError}s
     */
    interface Builder> {

        /**
         * Sets the message of the error using {@link String#format(String, Object...)} with the arguments
         *
         * @param message    the message
         * @param formatArgs the arguments to use
         *
         * @return this builder
         */
        B message(String message, Object... formatArgs);

        /**
         * This adds locations to the error
         *
         * @param locations the locations to add
         *
         * @return this builder
         */
        B locations(@Nullable List locations);

        /**
         * This adds a location to the error
         *
         * @param location the locations to add
         *
         * @return this builder
         */
        B location(@Nullable SourceLocation location);

        /**
         * Sets the path of the message
         *
         * @param path can be null
         *
         * @return this builder
         */
        B path(@Nullable ResultPath path);

        /**
         * Sets the path of the message
         *
         * @param path can be null
         *
         * @return this builder
         */
        B path(@Nullable List path);

        /**
         * Sets the {@link ErrorClassification} of the message
         *
         * @param errorType the error classification to use
         *
         * @return this builder
         */
        B errorType(ErrorClassification errorType);

        /**
         * Sets the extensions of the message
         *
         * @param extensions the extensions to use
         *
         * @return this builder
         */
        B extensions(@Nullable Map extensions);

        /**
         * @return a newly built GraphqlError
         */
        GraphQLError build();
    }
}