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  package org.apache.logging.log4j;
    18
    19  import java.io.Serializable;
    20
    21  /**
    22   *  Markers are objects that are used to add easily filterable information to log messages.
    23   *
    24   *  Markers can be hierarchical - each Marker may have a parent. This allows for broad categories
    25   *  being subdivided into more specific categories. An example might be a Marker named "Error" with
    26   *  children named "SystemError" and "ApplicationError".
    27   */
    28  public interface Marker extends Serializable {
    29
    30      /**
    31       * Returns the name of this Marker.
    32       * @return The name of the Marker.
    33       */
    34      String getName();
    35
    36      /**
    37       * Returns a list of parents of this Marker.
    38       * @return The parent Markers or {@code null} if this Marker has no parents.
    39       */
    40      Marker[] getParents();
    41
    42      /**
    43       * Indicates whether this Marker has references to any other Markers.
    44       * @return {@code true} if the Marker has parent Markers
    45       */
    46      boolean hasParents();
    47
    48      /**
    49       * Checks whether this Marker is an instance of the specified Marker.
    50       * @param m The Marker to check.
    51       * @return {@code true} if this Marker or one of its ancestors is the specified Marker, {@code false} otherwise.
    52       * @throws IllegalArgumentException if the argument is {@code null}
    53       */
    54      boolean isInstanceOf(Marker m);
    55
    56      /**
    57       * Checks whether this Marker is an instance of the specified Marker.
    58       * @param name The name of the Marker.
    59       * @return {@code true} if this Marker or one of its ancestors matches the specified name, {@code false} otherwise.
    60       * @throws IllegalArgumentException if the argument is {@code null}
    61       */
    62      boolean isInstanceOf(String name);
    63
    64      /**
    65       * Adds a Marker as a parent to this Marker.
    66       * @param markers The parent markers to add.
    67       * @return The current Marker object, thus allowing multiple adds to be concatenated.
    68       * @throws IllegalArgumentException if the argument is {@code null}
    69       */
    70      Marker addParents(Marker... markers);
    71
    72      /**
    73       * Replaces the set of parent Markers with the provided Markers.
    74       * @param markers The new set of parent Markers or {@code null} to clear the parents.
    75       * @return The current Marker object.
    76       */
    77      Marker setParents(Marker... markers);
    78
    79      /**
    80       * Removes the specified Marker as a parent of this Marker.
    81       * @param marker The marker to remove.
    82       * @return {@code true} if the marker was removed.
    83       * @throws IllegalArgumentException if the argument is {@code null}
    84       */
    85      boolean remove(Marker marker);
    86  }