    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements. See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License. You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017
    018    package org.apache.logging.log4j.core.config.plugins.visitors;
    019
    020    import java.lang.annotation.Annotation;
    021    import java.lang.reflect.Member;
    022
    023    import org.apache.logging.log4j.core.LogEvent;
    024    import org.apache.logging.log4j.core.config.Configuration;
    025    import org.apache.logging.log4j.core.config.Node;
    026    import org.apache.logging.log4j.core.lookup.StrSubstitutor;
    027
    028    /**
    029     * Visitor strategy for parsing data from a {@link Node}, doing any relevant type conversion, and returning a
    030     * parsed value for that variable. Implementations must be constructable using the default constructor.
    031     *
    032     * @param <A> the Annotation type.
    033     */
    034    public interface PluginVisitor<A extends Annotation> {
    035
    036        /**
    037         * Sets the Annotation to be used for this. If the given Annotation is not compatible with this class's type, then
    038         * it is ignored.
    039         *
    040         * @param annotation the Annotation instance.
    041         * @return {@code this}.
    042         * @throws NullPointerException if the argument is {@code null}.
    043         */
    044        PluginVisitor<A> setAnnotation(Annotation annotation);
    045
    046        /**
    047         * Sets the list of aliases to use for this visit. No aliases are required, however.
    048         *
    049         * @param aliases the list of aliases to use.
    050         * @return {@code this}.
    051         */
    052        PluginVisitor<A> setAliases(String... aliases);
    053
    054        /**
    055         * Sets the class to convert the plugin value to on this visit. This should correspond with a class obtained from
    056         * a factory method or builder class field. Not all PluginVisitor implementations may need this value.
    057         *
    058         * @param conversionType the type to convert the plugin string to (if applicable).
    059         * @return {@code this}.
    060         * @throws NullPointerException if the argument is {@code null}.
    061         */
    062        PluginVisitor<A> setConversionType(Class<?> conversionType);
    063
    064        /**
    065         * Sets the StrSubstitutor to use for converting raw strings before type conversion. Generally obtained from a
    066         * {@link org.apache.logging.log4j.core.config.Configuration}.
    067         *
    068         * @param substitutor the StrSubstitutor to use on plugin values.
    069         * @return {@code this}.
    070         * @throws NullPointerException if the argument is {@code null}.
    071         */
    072        PluginVisitor<A> setStrSubstitutor(StrSubstitutor substitutor);
    073
    074        /**
    075         * Sets the Member that this visitor is being used for injection upon. For instance, this could be the Field
    076         * that is being used for injecting a value, or it could be the factory method being used to inject parameters
    077         * into.
    078         *
    079         * @param member the member this visitor is parsing a value for.
    080         * @return {@code this}.
    081         */
    082        PluginVisitor<A> setMember(Member member);
    083
    084        /**
    085         * Visits a Node to obtain a value for constructing a Plugin object.
    086         *
    087         * @param configuration the current Configuration.
    088         * @param node          the current Node corresponding to the Plugin object being created.
    089         * @param event         the current LogEvent that caused this Plugin object to be made (optional).
    090         * @param log           the StringBuilder being used to build a debug message.
    091         * @return the converted value to be used for Plugin creation.
    092         */
    093        Object visit(Configuration configuration, Node node, LogEvent event, StringBuilder log);
    094    }