io.mats3.api.intercept.MatsInterceptable Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mats-intercept-api Show documentation
Extension to the Mats^3 API which adds interception capabilities.
There is a newer version: 0.19.22-2024-11-09
package io.mats3.api.intercept;

import java.util.List;
import java.util.Optional;

import io.mats3.MatsEndpoint.EndpointConfig;
import io.mats3.MatsInitiator.MatsInitiate;

/**
 * Specifies methods that an interceptable MatsFactory must provide.
 *
 * @author Endre Stølsvik - 2021-02-07 & 2021-02-19 13:18 - http://endre.stolsvik.com
 */
public interface MatsInterceptable {
    // ===== Initiation

    void addInitiationInterceptor(MatsInitiateInterceptor initiateInterceptor);

    List getInitiationInterceptors();

     Optional getInitiationInterceptor(Class interceptorClass);

    void removeInitiationInterceptor(MatsInitiateInterceptor initiateInterceptor);

    // ===== Stage

    void addStageInterceptor(MatsStageInterceptor stageInterceptor);

    List getStageInterceptors();

     Optional getStageInterceptor(Class interceptorClass);

    void removeStageInterceptor(MatsStageInterceptor stageInterceptor);

    /**
     * Marker interface to denote a logging interceptor. The MatsFactory will only allow one such singleton interceptor,
     * and remove any previously installed if subsequently installing another.
     */
    interface MatsLoggingInterceptor {
        /**
         * If this key is present on the {@link MatsInitiate#setTraceProperty(String, Object) TraceProperties} of a Mats
         * Flow, with the value {@link Boolean#TRUE}, no ordinary log lines should be emitted while initiating or stage
         * processing the Mats Flow, assuming that the implicated endpoints
         * {@link #SUPPRESS_LOGGING_ENDPOINT_ALLOWS_ATTRIBUTE_KEY allows} logging suppression. This is only to be used
         * for frequent system messages that otherwise would swamp the log, and should never be used for ordinary
         * processing.
         * 
         * Note wrt. suppression of initiation logging: An outgoing message starts a Mats Flow. It is the message that
         * holds the TraceProperty saying that logging should be suppressed. Three things: 1. Contrasted to endpoints,
         * initiations do not have an {@link #SUPPRESS_LOGGING_ENDPOINT_ALLOWS_ATTRIBUTE_KEY "allow"} concept, as it
         * makes no sense security wise since the initiator could just change the allowance. 2. If multiple messages are
         * initiated, then they all must agree of suppression for the initiation log lines to be suppressed. 3. If you
         * initiate, but do not send any messages after all (inside the initiation you find that there is nothing to
         * do), then it is impossible to suppress logging. Thus, you should instead perform whatever checking to decide
         * whether to send a message before going into initiation.
         * 

         * Note: The MatsMetricsLoggingInterceptor has logic whereby every X minutes, the number of
         * suppressed logs are output (if any), grouped into matsFactory/initApp/initiatorId/stageId, so that it is
         * possible to assert liveliness of the system, and also get an idea of how heavy usage it leads to.
         * 
         * Note: Suppression of logging effectively removes these initiations and processing from any aggregate metrics
         * based on the log system, e.g. doing "number of message per second" in Kibana will lose out on these messages
         * since they aren't logged (except for the aggregate every X minutes mentioned above). Metrics in form of
         * MatsMicrometerInterceptor are not affected.
         *
         * @see #SUPPRESS_LOGGING_ENDPOINT_ALLOWS_ATTRIBUTE_KEY
         */
        String SUPPRESS_LOGGING_TRACE_PROPERTY_KEY = "mats.SuppressLogging";

        /**
         * {@link #SUPPRESS_LOGGING_TRACE_PROPERTY_KEY Suppression of loglines} will only be done if the affected
         * endpoints allows it. Allowance is done by setting an {@link EndpointConfig#setAttribute(String, Object)
         * EndpointConfig attribute} for the allowing Endpoint with this as key, with the value {@link Boolean#TRUE}.
         *
         * @see #SUPPRESS_LOGGING_TRACE_PROPERTY_KEY
         */
        String SUPPRESS_LOGGING_ENDPOINT_ALLOWS_ATTRIBUTE_KEY = "mats.SuppressLoggingAllowed";
    }

    /**
     * Marker interface to denote a metrics interceptor. The MatsFactory will only allow one such singleton interceptor,
     * and remove any previously installed if subsequently installing another.
     */
    interface MatsMetricsInterceptor {
        /**
         * When measuring "initiate complete", and the initiation ends up sending no messages, there is no
         * InitiatorId to include. This is a constant that can be used instead. Value is
         * "_no_outgoing_messages_". (Note that this also holds for logging, but it came up first with
         * pure metrics).
         */
        String INITIATOR_ID_WHEN_NO_OUTGOING_MESSAGES = "_no_outgoing_messages_";

    }
}