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 public boolean hasChildren(); 084 085 /** 086 * Does this marker have any references? 087 * 088 * @return true if this marker has one or more references, false otherwise. 089 */ 090 public boolean hasReferences(); 091 092 /** 093 * Returns an Iterator which can be used to iterate over the references of this 094 * marker. An empty iterator is returned when this marker has no references. 095 * 096 * @return Iterator over the references of this marker 097 */ 098 public Iterator<Marker> iterator(); 099 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}