• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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      */
getName()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      */
add(Marker reference)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      */
remove(Marker reference)78     public boolean remove(Marker reference);
79 
80     /**
81      * @deprecated Replaced by {@link #hasReferences()}.
82      */
hasChildren()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      */
hasReferences()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      */
iterator()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      */
contains(Marker other)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      */
contains(String name)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      */
equals(Object o)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      */
hashCode()140     public int hashCode();
141 
142 }
143