1   /* 
2    * Copyright (c) 2004-2007 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
32   * logging system Implementations of SLF4J determine how information
33   * conveyed by markers are used, if at all. In particular, many
34   * conforming logging systems ignore marker data.
35   * 
36   * <p>Markers can contain child markers, which in turn  can contain children 
37   * of their own.
38   *
39   * @author Ceki G&uuml;lc&uuml;
40   */
41  public interface Marker extends Serializable {
42   
43    /**
44     * This constant represents any marker, including a null marker.
45     */
46    public static final String ANY_MARKER = "*";
47    
48    /**
49     * This constant represents any non-null marker.
50     */
51    public static final String ANY_NON_NULL_MARKER = "+";
52    
53    
54    /**
55     * Get the name of this Marker.
56     * @return name of marker
57     */ 
58    public String getName();
59  
60    /**
61     * Add a child Marker to this Marker.
62     * @param child a child marker
63     */
64    public void add(Marker child);
65    
66    /**
67     * Remove a child Marker.
68     * @param child the child Marker to remove
69     * @return true if child could be found and removed, false otherwise.
70     */
71    public boolean remove(Marker child);
72    
73    /**
74     * Does this marker have children?
75     * @return true if this marker has children, false otherwise.
76     */
77    public boolean hasChildren();
78    
79    /**
80     * Returns an Iterator which can be used to iterate over the
81     * children of this marker. An empty iterator is returned when this
82     * marker has no children.
83     * 
84     * @return Iterator over the children of this marker
85     */
86    public Iterator iterator();
87    
88    /**
89     * Does this marker contain the 'other' marker? Marker A is defined to 
90     * contain marker B, if A == B or if B is a child of A. 
91     * 
92     * @param other The marker to test for inclusion.
93     * @throws IllegalArgumentException if 'other' is null
94     * @return Whether this marker contains the other marker.
95     */
96    public boolean contains(Marker other);
97  
98    
99    
100   /**
101    * Does this marker contain the marker named 'name'? 
102    * 
103    * If 'name' is null the returned value is always false.
104    * 
105    * @param other The marker to test for inclusion.
106    * @return Whether this marker contains the other marker.
107    */
108   public boolean contains(String name);
109   
110 //  void makeImmutable();
111 //  public boolean isImmutable();
112 }