io.rxmicro.rest.client.RestClientGeneratorConfig Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 2020. https://rxmicro.io
 *
 * 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 io.rxmicro.rest.client;

import io.rxmicro.rest.model.ClientExchangeFormatModule;
import io.rxmicro.rest.model.GenerateOption;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.MODULE;
import static java.lang.annotation.RetentionPolicy.CLASS;

/**
 * Allows configuring the process of code generation by the {@code RxMicro Annotation Processor} for REST clients.
 *
 * 
 * To configure the process of code generation by the {@code RxMicro Annotation Processor}
 * developer must annotated a module descriptor {@code module-info.java} by this annotation.
 *
 * @author nedis
 * @since 0.1
 */
@Documented
@Retention(CLASS)
@Target({MODULE, ANNOTATION_TYPE})
public @interface RestClientGeneratorConfig {

    /**
     * Allows specifying the format for message exchange with a server.
     *
     * @return the message exchange format.
     */
    ClientExchangeFormatModule exchangeFormat() default ClientExchangeFormatModule.AUTO_DETECT;

    /**
     * Allows enabling/disabling the option of generating HTTP request validators for all REST client methods in the project.
     *
     * 

     * By default generated request validators are not invoked by the REST client.
     * To enable the validation of HTTP requests by the generated validators it is necessary to enable additional validations:
     * {@link RestClientConfig#setEnableAdditionalValidations(boolean)}.
     *
     * 
     * Request validation is useful feature for development environment only, so to enable this feature it is necessary
     * to configure the RxMicro framework manually. (See above how to do it)
     *
     * @return {@link GenerateOption#AUTO_DETECT} if validators must be generated only if the developer adds the
     *              {@code rxmicro.validation} module to the {@code module-info.java} descriptor.
     *         {@link GenerateOption#DISABLED} if validators must not be generated by the {@code RxMicro Annotation Processor}.
     */
    GenerateOption generateRequestValidators() default GenerateOption.AUTO_DETECT;

    /**
     * Specifies how the HTTP request parameters should be checked.
     *
     * @return {@link RequestValidationMode#THROW_EXCEPTION} if it is necessary to catch the exception
     *         {@link RequestValidationMode#RETURN_ERROR_SIGNAL} if error handling should be performed in reactive style
     */
    RequestValidationMode requestValidationMode() default RequestValidationMode.THROW_EXCEPTION;

    /**
     * Allows enabling/disabling the option of generating HTTP response validators for all REST client methods in the project.
     *
     * @return {@link GenerateOption#AUTO_DETECT} if validators must be generated only if the developer adds the
     *              {@code rxmicro.validation} module to the {@code module-info.java} descriptor.
     *         {@link GenerateOption#DISABLED} if validators must not be generated by the {@code RxMicro Annotation Processor}.
     */
    GenerateOption generateResponseValidators() default GenerateOption.AUTO_DETECT;

    /**
     * Provides supported request validation modes for REST clients.
     *
     * @author nedis
     * @since 0.1
     */
    enum RequestValidationMode {

        /**
         * it is necessary to catch the exception.
         */
        THROW_EXCEPTION,

        /**
         * error handling should be performed in reactive style.
         */
        RETURN_ERROR_SIGNAL
    }
}