001/** 002 * Copyright (c) 2004-2011 QOS.ch 003 * All rights reserved. 004 * 005 * Permission is hereby granted, free of charge, to any person obtaining 006 * a copy of this software and associated documentation files (the 007 * "Software"), to deal in the Software without restriction, including 008 * without limitation the rights to use, copy, modify, merge, publish, 009 * distribute, sublicense, and/or sell copies of the Software, and to 010 * permit persons to whom the Software is furnished to do so, subject to 011 * the following conditions: 012 * 013 * The above copyright notice and this permission notice shall be 014 * included in all copies or substantial portions of the Software. 015 * 016 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 017 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 018 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 019 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 020 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 021 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 022 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 023 * 024 */ 025package org.slf4j; 026 027import java.io.Serializable; 028import java.util.Iterator; 029 030/** 031 * Markers are named objects used to enrich log statements. Conforming logging 032 * system Implementations of SLF4J determine how information conveyed by markers 033 * are used, if at all. In particular, many conforming logging systems ignore 034 * marker data. 035 * 036 * <p> 037 * Markers can contain references to other markers, which in turn may contain 038 * references of their own. 039 * 040 * @author Ceki Gülcü 041 */ 042public interface Marker extends Serializable { 043 044 /** 045 * This constant represents any marker, including a null marker. 046 */ 047 public final String ANY_MARKER = "*"; 048 049 /** 050 * This constant represents any non-null marker. 051 */ 052 public final String ANY_NON_NULL_MARKER = "+"; 053 054 /** 055 * Get the name of this Marker. 056 * 057 * @return name of marker 058 */ 059 public String getName(); 060 061 /** 062 * Add a reference to another Marker. 063 * 064 * @param reference 065 * a reference to another marker 066 * @throws IllegalArgumentException 067 * if 'reference' is null 068 */ 069 public void add(Marker reference); 070 071 /** 072 * Remove a marker reference. 073 * 074 * @param reference 075 * the marker reference to remove 076 * @return true if reference could be found and removed, false otherwise. 077 */ 078 public boolean remove(Marker reference); 079 080 /** 081 * @deprecated Replaced by {@link #hasReferences()}. 082 */ 083 @Deprecated 084 public boolean hasChildren(); 085 086 /** 087 * Does this marker have any references? 088 * 089 * @return true if this marker has one or more references, false otherwise. 090 */ 091 public boolean hasReferences(); 092 093 /** 094 * Returns an Iterator which can be used to iterate over the references of this 095 * marker. An empty iterator is returned when this marker has no references. 096 * 097 * @return Iterator over the references of this marker 098 */ 099 public Iterator<Marker> iterator(); 100 101 /** 102 * Does this marker contain a reference to the 'other' marker? Marker A is defined 103 * to contain marker B, if A == B or if B is referenced by A, or if B is referenced 104 * by any one of A's references (recursively). 105 * 106 * @param other 107 * The marker to test for inclusion. 108 * @throws IllegalArgumentException 109 * if 'other' is null 110 * @return Whether this marker contains the other marker. 111 */ 112 public boolean contains(Marker other); 113 114 /** 115 * Does this marker contain the marker named 'name'? 116 * 117 * If 'name' is null the returned value is always false. 118 * 119 * @param name The marker name to test for inclusion. 120 * @return Whether this marker contains the other marker. 121 */ 122 public boolean contains(String name); 123 124 /** 125 * Markers are considered equal if they have the same name. 126 * 127 * @param o 128 * @return true, if this.name equals o.name 129 * 130 * @since 1.5.1 131 */ 132 public boolean equals(Object o); 133 134 /** 135 * Compute the hash code based on the name of this marker. 136 * Note that markers are considered equal if they have the same name. 137 * 138 * @return the computed hashCode 139 * @since 1.5.1 140 */ 141 public int hashCode(); 142 143}