1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.logging.log4j.core.config.plugins.visitors;
19
20 import java.lang.annotation.Annotation;
21 import java.lang.reflect.Member;
22
23 import org.apache.logging.log4j.core.LogEvent;
24 import org.apache.logging.log4j.core.config.Configuration;
25 import org.apache.logging.log4j.core.config.Node;
26 import org.apache.logging.log4j.core.lookup.StrSubstitutor;
27
28 /**
29 * Visitor strategy for parsing data from a {@link Node}, doing any relevant type conversion, and returning a
30 * parsed value for that variable. Implementations must be constructable using the default constructor.
31 *
32 * @param <A> the Annotation type.
33 */
34 public interface PluginVisitor<A extends Annotation> {
35
36 /**
37 * Sets the Annotation to be used for this. If the given Annotation is not compatible with this class's type, then
38 * it is ignored.
39 *
40 * @param annotation the Annotation instance.
41 * @return {@code this}.
42 * @throws NullPointerException if the argument is {@code null}.
43 */
44 PluginVisitor<A> setAnnotation(Annotation annotation);
45
46 /**
47 * Sets the list of aliases to use for this visit. No aliases are required, however.
48 *
49 * @param aliases the list of aliases to use.
50 * @return {@code this}.
51 */
52 PluginVisitor<A> setAliases(String... aliases);
53
54 /**
55 * Sets the class to convert the plugin value to on this visit. This should correspond with a class obtained from
56 * a factory method or builder class field. Not all PluginVisitor implementations may need this value.
57 *
58 * @param conversionType the type to convert the plugin string to (if applicable).
59 * @return {@code this}.
60 * @throws NullPointerException if the argument is {@code null}.
61 */
62 PluginVisitor<A> setConversionType(Class<?> conversionType);
63
64 /**
65 * Sets the StrSubstitutor to use for converting raw strings before type conversion. Generally obtained from a
66 * {@link org.apache.logging.log4j.core.config.Configuration}.
67 *
68 * @param substitutor the StrSubstitutor to use on plugin values.
69 * @return {@code this}.
70 * @throws NullPointerException if the argument is {@code null}.
71 */
72 PluginVisitor<A> setStrSubstitutor(StrSubstitutor substitutor);
73
74 /**
75 * Sets the Member that this visitor is being used for injection upon. For instance, this could be the Field
76 * that is being used for injecting a value, or it could be the factory method being used to inject parameters
77 * into.
78 *
79 * @param member the member this visitor is parsing a value for.
80 * @return {@code this}.
81 */
82 PluginVisitor<A> setMember(Member member);
83
84 /**
85 * Visits a Node to obtain a value for constructing a Plugin object.
86 *
87 * @param configuration the current Configuration.
88 * @param node the current Node corresponding to the Plugin object being created.
89 * @param event the current LogEvent that caused this Plugin object to be made (optional).
90 * @param log the StringBuilder being used to build a debug message.
91 * @return the converted value to be used for Plugin creation.
92 */
93 Object visit(Configuration configuration, Node node, LogEvent event, StringBuilder log);
94 }