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ülcü 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