View Javadoc

    1   /**
    2    * Copyright (c) 2004-2011 QOS.ch
    3    * All rights reserved.
    4    *
    5    * Permission is hereby granted, free  of charge, to any person obtaining
    6    * a  copy  of this  software  and  associated  documentation files  (the
    7    * "Software"), to  deal in  the Software without  restriction, including
    8    * without limitation  the rights to  use, copy, modify,  merge, publish,
    9    * distribute,  sublicense, and/or sell  copies of  the Software,  and to
    10   * permit persons to whom the Software  is furnished to do so, subject to
    11   * the following conditions:
    12   *
    13   * The  above  copyright  notice  and  this permission  notice  shall  be
    14   * included in all copies or substantial portions of the Software.
    15   *
    16   * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
    17   * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
    18   * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
    19   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
    20   * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
    21   * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
    22   * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    23   *
    24   */
    25  package org.slf4j;
    26
    27  import java.io.Serializable;
    28  import java.util.Iterator;
    29
    30  /**
    31   * Markers are named objects used to enrich log statements. Conforming logging
    32   * system Implementations of SLF4J determine how information conveyed by markers
    33   * are used, if at all. In particular, many conforming logging systems ignore
    34   * marker data.
    35   *
    36   * <p>
    37   * Markers can contain references to other markers, which in turn may contain
    38   * references of their own.
    39   *
    40   * @author Ceki G&uuml;lc&uuml;
    41   */
    42  public interface Marker extends Serializable {
    43
    44      /**
    45       * This constant represents any marker, including a null marker.
    46       */
    47      public final String ANY_MARKER = "*";
    48
    49      /**
    50       * This constant represents any non-null marker.
    51       */
    52      public final String ANY_NON_NULL_MARKER = "+";
    53
    54      /**
    55       * Get the name of this Marker.
    56       *
    57       * @return name of marker
    58       */
    59      public String getName();
    60
    61      /**
    62       * Add a reference to another Marker.
    63       *
    64       * @param reference
    65       *                a reference to another marker
    66       * @throws IllegalArgumentException
    67       *                 if 'reference' is null
    68       */
    69      public void add(Marker reference);
    70
    71      /**
    72       * Remove a marker reference.
    73       *
    74       * @param reference
    75       *                the marker reference to remove
    76       * @return true if reference could be found and removed, false otherwise.
    77       */
    78      public boolean remove(Marker reference);
    79
    80      /**
    81       * @deprecated Replaced by {@link #hasReferences()}.
    82       */
    83      public boolean hasChildren();
    84
    85      /**
    86       * Does this marker have any references?
    87       *
    88       * @return true if this marker has one or more references, false otherwise.
    89       */
    90      public boolean hasReferences();
    91
    92      /**
    93       * Returns an Iterator which can be used to iterate over the references of this
    94       * marker. An empty iterator is returned when this marker has no references.
    95       *
    96       * @return Iterator over the references of this marker
    97       */
    98      public Iterator<Marker> iterator();
    99
    100     /**
    101      * Does this marker contain a reference to the 'other' marker? Marker A is defined
    102      * to contain marker B, if A == B or if B is referenced by A, or if B is referenced
    103      * by any one of A's references (recursively).
    104      *
    105      * @param other
    106      *                The marker to test for inclusion.
    107      * @throws IllegalArgumentException
    108      *                 if 'other' is null
    109      * @return Whether this marker contains the other marker.
    110      */
    111     public boolean contains(Marker other);
    112
    113     /**
    114      * Does this marker contain the marker named 'name'?
    115      *
    116      * If 'name' is null the returned value is always false.
    117      *
    118      * @param name The marker name to test for inclusion.
    119      * @return Whether this marker contains the other marker.
    120      */
    121     public boolean contains(String name);
    122
    123     /**
    124      * Markers are considered equal if they have the same name.
    125      *
    126      * @param o
    127      * @return true, if this.name equals o.name
    128      *
    129      * @since 1.5.1
    130      */
    131     public boolean equals(Object o);
    132
    133     /**
    134      * Compute the hash code based on the name of this marker.
    135      * Note that markers are considered equal if they have the same name.
    136      *
    137      * @return the computed hashCode
    138      * @since 1.5.1
    139      */
    140     public int hashCode();
    141
    142 }