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.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  }