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 }