View Javadoc
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.util;
19  
20  import java.lang.annotation.Annotation;
21  import java.lang.reflect.AccessibleObject;
22  import java.lang.reflect.Field;
23  import java.lang.reflect.InvocationTargetException;
24  import java.lang.reflect.Method;
25  import java.lang.reflect.Modifier;
26  import java.util.Collection;
27  import java.util.List;
28  import java.util.Map;
29  import java.util.Objects;
30  
31  import org.apache.logging.log4j.Logger;
32  import org.apache.logging.log4j.core.LogEvent;
33  import org.apache.logging.log4j.core.config.Configuration;
34  import org.apache.logging.log4j.core.config.ConfigurationException;
35  import org.apache.logging.log4j.core.config.Node;
36  import org.apache.logging.log4j.core.config.plugins.PluginAliases;
37  import org.apache.logging.log4j.core.config.plugins.PluginBuilderFactory;
38  import org.apache.logging.log4j.core.config.plugins.PluginFactory;
39  import org.apache.logging.log4j.core.config.plugins.validation.ConstraintValidator;
40  import org.apache.logging.log4j.core.config.plugins.validation.ConstraintValidators;
41  import org.apache.logging.log4j.core.config.plugins.visitors.PluginVisitor;
42  import org.apache.logging.log4j.core.config.plugins.visitors.PluginVisitors;
43  import org.apache.logging.log4j.core.util.Builder;
44  import org.apache.logging.log4j.core.util.ReflectionUtil;
45  import org.apache.logging.log4j.core.util.TypeUtil;
46  import org.apache.logging.log4j.status.StatusLogger;
47  import org.apache.logging.log4j.util.StringBuilders;
48  
49  /**
50   * Builder class to instantiate and configure a Plugin object using a PluginFactory method or PluginBuilderFactory
51   * builder class.
52   */
53  public class PluginBuilder implements Builder<Object> {
54  
55      private static final Logger LOGGER = StatusLogger.getLogger();
56  
57      private final PluginType<?> pluginType;
58      private final Class<?> clazz;
59  
60      private Configuration configuration;
61      private Node node;
62      private LogEvent event;
63  
64      /**
65       * Constructs a PluginBuilder for a given PluginType.
66       *
67       * @param pluginType type of plugin to configure
68       */
69      public PluginBuilder(final PluginType<?> pluginType) {
70          this.pluginType = pluginType;
71          this.clazz = pluginType.getPluginClass();
72      }
73  
74      /**
75       * Specifies the Configuration to use for constructing the plugin instance.
76       *
77       * @param configuration the configuration to use.
78       * @return {@code this}
79       */
80      public PluginBuilder withConfiguration(final Configuration configuration) {
81          this.configuration = configuration;
82          return this;
83      }
84  
85      /**
86       * Specifies the Node corresponding to the plugin object that will be created.
87       *
88       * @param node the plugin configuration node to use.
89       * @return {@code this}
90       */
91      public PluginBuilder withConfigurationNode(final Node node) {
92          this.node = node;
93          return this;
94      }
95  
96      /**
97       * Specifies the LogEvent that may be used to provide extra context for string substitutions.
98       *
99       * @param event the event to use for extra information.
100      * @return {@code this}
101      */
102     public PluginBuilder forLogEvent(final LogEvent event) {
103         this.event = event;
104         return this;
105     }
106 
107     /**
108      * Builds the plugin object.
109      *
110      * @return the plugin object or {@code null} if there was a problem creating it.
111      */
112     @Override
113     public Object build() {
114         verify();
115         // first try to use a builder class if one is available
116         try {
117             LOGGER.debug("Building Plugin[name={}, class={}]. Searching for builder factory method...", pluginType.getElementName(),
118                     pluginType.getPluginClass().getName());
119             final Builder<?> builder = createBuilder(this.clazz);
120             if (builder != null) {
121                 injectFields(builder);
122                 final Object result = builder.build();
123                 LOGGER.debug("Built Plugin[name={}] OK from builder factory method.", pluginType.getElementName());
124                 return result;
125             }
126         } catch (final Exception e) {
127             LOGGER.error("Unable to inject fields into builder class for plugin type {}, element {}.", this.clazz,
128                 node.getName(), e);
129         }
130         // or fall back to factory method if no builder class is available
131         try {
132             LOGGER.debug("Still building Plugin[name={}, class={}]. Searching for factory method...",
133                     pluginType.getElementName(), pluginType.getPluginClass().getName());
134             final Method factory = findFactoryMethod(this.clazz);
135             final Object[] params = generateParameters(factory);
136             final Object plugin = factory.invoke(null, params);
137             LOGGER.debug("Built Plugin[name={}] OK from factory method.", pluginType.getElementName());
138             return plugin;
139         } catch (final Exception e) {
140             LOGGER.error("Unable to invoke factory method in class {} for element {}.", this.clazz, this.node.getName(),
141                 e);
142             return null;
143         }
144     }
145 
146     private void verify() {
147         Objects.requireNonNull(this.configuration, "No Configuration object was set.");
148         Objects.requireNonNull(this.node, "No Node object was set.");
149     }
150 
151     private static Builder<?> createBuilder(final Class<?> clazz)
152         throws InvocationTargetException, IllegalAccessException {
153         for (final Method method : clazz.getDeclaredMethods()) {
154             if (method.isAnnotationPresent(PluginBuilderFactory.class) &&
155                 Modifier.isStatic(method.getModifiers()) &&
156                 TypeUtil.isAssignable(Builder.class, method.getGenericReturnType())) {
157                 ReflectionUtil.makeAccessible(method);
158                 final Builder<?> builder = (Builder<?>) method.invoke(null);
159                 LOGGER.debug("Found builder factory method [{}]: {}.", method.getName(), method);
160                 return builder;
161             }
162         }
163         LOGGER.debug("No builder factory method found in class {}. Going to try finding a factory method instead.",
164             clazz.getName());
165         return null;
166     }
167 
168     private void injectFields(final Builder<?> builder) throws IllegalAccessException {
169         final Field[] fields = builder.getClass().getDeclaredFields();
170         AccessibleObject.setAccessible(fields, true);
171         final StringBuilder log = new StringBuilder();
172         boolean invalid = false;
173         for (final Field field : fields) {
174             log.append(log.length() == 0 ? "with params(" : ", ");
175             final Annotation[] annotations = field.getDeclaredAnnotations();
176             final String[] aliases = extractPluginAliases(annotations);
177             for (final Annotation a : annotations) {
178                 if (a instanceof PluginAliases) {
179                     continue; // already processed
180                 }
181                 final PluginVisitor<? extends Annotation> visitor =
182                     PluginVisitors.findVisitor(a.annotationType());
183                 if (visitor != null) {
184                     final Object value = visitor.setAliases(aliases)
185                         .setAnnotation(a)
186                         .setConversionType(field.getType())
187                         .setStrSubstitutor(configuration.getStrSubstitutor())
188                         .setMember(field)
189                         .visit(configuration, node, event, log);
190                     // don't overwrite default values if the visitor gives us no value to inject
191                     if (value != null) {
192                         field.set(builder, value);
193                     }
194                 }
195             }
196             final Collection<ConstraintValidator<?>> validators =
197                 ConstraintValidators.findValidators(annotations);
198             final Object value = field.get(builder);
199             for (final ConstraintValidator<?> validator : validators) {
200                 if (!validator.isValid(value)) {
201                     invalid = true;
202                 }
203             }
204         }
205         if (log.length() > 0) {
206             log.append(')');
207         }
208         LOGGER.debug("Calling build() on class {} for element {} {}", builder.getClass(), node.getName(),
209             log.toString());
210         if (invalid) {
211             throw new ConfigurationException("Arguments given for element " + node.getName() + " are invalid");
212         }
213         checkForRemainingAttributes();
214         verifyNodeChildrenUsed();
215     }
216 
217     private static Method findFactoryMethod(final Class<?> clazz) {
218         for (final Method method : clazz.getDeclaredMethods()) {
219             if (method.isAnnotationPresent(PluginFactory.class) &&
220                 Modifier.isStatic(method.getModifiers())) {
221                 LOGGER.debug("Found factory method [{}]: {}.", method.getName(), method);
222                 ReflectionUtil.makeAccessible(method);
223                 return method;
224             }
225         }
226         throw new IllegalStateException("No factory method found for class " + clazz.getName());
227     }
228 
229     private Object[] generateParameters(final Method factory) {
230         final StringBuilder log = new StringBuilder();
231         final Class<?>[] types = factory.getParameterTypes();
232         final Annotation[][] annotations = factory.getParameterAnnotations();
233         final Object[] args = new Object[annotations.length];
234         boolean invalid = false;
235         for (int i = 0; i < annotations.length; i++) {
236             log.append(log.length() == 0 ? "with params(" : ", ");
237             final String[] aliases = extractPluginAliases(annotations[i]);
238             for (final Annotation a : annotations[i]) {
239                 if (a instanceof PluginAliases) {
240                     continue; // already processed
241                 }
242                 final PluginVisitor<? extends Annotation> visitor = PluginVisitors.findVisitor(
243                     a.annotationType());
244                 if (visitor != null) {
245                     final Object value = visitor.setAliases(aliases)
246                         .setAnnotation(a)
247                         .setConversionType(types[i])
248                         .setStrSubstitutor(configuration.getStrSubstitutor())
249                         .setMember(factory)
250                         .visit(configuration, node, event, log);
251                     // don't overwrite existing values if the visitor gives us no value to inject
252                     if (value != null) {
253                         args[i] = value;
254                     }
255                 }
256             }
257             final Collection<ConstraintValidator<?>> validators =
258                 ConstraintValidators.findValidators(annotations[i]);
259             final Object value = args[i];
260             for (final ConstraintValidator<?> validator : validators) {
261                 if (!validator.isValid(value)) {
262                     invalid = true;
263                 }
264             }
265         }
266         if (log.length() > 0) {
267             log.append(')');
268         }
269         checkForRemainingAttributes();
270         verifyNodeChildrenUsed();
271         LOGGER.debug("Calling {} on class {} for element {} {}", factory.getName(), clazz.getName(), node.getName(),
272             log.toString());
273         if (invalid) {
274             throw new ConfigurationException("Arguments given for element " + node.getName() + " are invalid");
275         }
276         return args;
277     }
278 
279     private static String[] extractPluginAliases(final Annotation... parmTypes) {
280         String[] aliases = null;
281         for (final Annotation a : parmTypes) {
282             if (a instanceof PluginAliases) {
283                 aliases = ((PluginAliases) a).value();
284             }
285         }
286         return aliases;
287     }
288 
289     private void checkForRemainingAttributes() {
290         final Map<String, String> attrs = node.getAttributes();
291         if (!attrs.isEmpty()) {
292             final StringBuilder sb = new StringBuilder();
293             for (final String key : attrs.keySet()) {
294                 if (sb.length() == 0) {
295                     sb.append(node.getName());
296                     sb.append(" contains ");
297                     if (attrs.size() == 1) {
298                         sb.append("an invalid element or attribute ");
299                     } else {
300                         sb.append("invalid attributes ");
301                     }
302                 } else {
303                     sb.append(", ");
304                 }
305                 StringBuilders.appendDqValue(sb, key);
306             }
307             LOGGER.error(sb.toString());
308         }
309     }
310 
311     private void verifyNodeChildrenUsed() {
312         final List<Node> children = node.getChildren();
313         if (!(pluginType.isDeferChildren() || children.isEmpty())) {
314             for (final Node child : children) {
315                 final String nodeType = node.getType().getElementName();
316                 final String start = nodeType.equals(node.getName()) ? node.getName() : nodeType + ' ' + node.getName();
317                 LOGGER.error("{} has no parameter that matches element {}", start, child.getName());
318             }
319         }
320     }
321 }