17ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu/** 27ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu * Copyright (c) 2004-2011 QOS.ch 388c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * All rights reserved. 47ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu * 588c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * Permission is hereby granted, free of charge, to any person obtaining 688c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * a copy of this software and associated documentation files (the 788c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * "Software"), to deal in the Software without restriction, including 888c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * without limitation the rights to use, copy, modify, merge, publish, 988c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * distribute, sublicense, and/or sell copies of the Software, and to 1088c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * permit persons to whom the Software is furnished to do so, subject to 1188c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * the following conditions: 127ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu * 1388c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * The above copyright notice and this permission notice shall be 1488c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * included in all copies or substantial portions of the Software. 157ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu * 1688c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 1788c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 1888c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 1988c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 2088c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 2188c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 2288c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 237ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu * 2488c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu */ 2588c4c456766193e012eb890e2208473d99b91f83Ceki Gulcupackage org.slf4j; 2688c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 2788c4c456766193e012eb890e2208473d99b91f83Ceki Gulcuimport java.io.Serializable; 2888c4c456766193e012eb890e2208473d99b91f83Ceki Gulcuimport java.util.Iterator; 2988c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 3088c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu/** 319f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * Markers are named objects used to enrich log statements. Conforming logging 3288c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * system Implementations of SLF4J determine how information conveyed by markers 339f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * are used, if at all. In particular, many conforming logging systems ignore 3488c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * marker data. 3588c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * 3688c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * <p> 3788c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * Markers can contain references to other markers, which in turn may contain 3888c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * references of their own. 3988c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * 4088c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu * @author Ceki Gülcü 4188c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu */ 4288c4c456766193e012eb890e2208473d99b91f83Ceki Gulcupublic interface Marker extends Serializable { 4388c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 4431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 4531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * This constant represents any marker, including a null marker. 4631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 4731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public final String ANY_MARKER = "*"; 4888c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 4931212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 5031212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * This constant represents any non-null marker. 5131212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 5231212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public final String ANY_NON_NULL_MARKER = "+"; 5388c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 5431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 5531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Get the name of this Marker. 5631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 5731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @return name of marker 5831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 5931212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public String getName(); 6088c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 6131212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 6231212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Add a reference to another Marker. 6331212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 6431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @param reference 6531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * a reference to another marker 6631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @throws IllegalArgumentException 6731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * if 'reference' is null 6831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 6931212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public void add(Marker reference); 7088c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 7131212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 7231212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Remove a marker reference. 7331212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 7431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @param reference 7531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * the marker reference to remove 7631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @return true if reference could be found and removed, false otherwise. 7731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 7831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public boolean remove(Marker reference); 7988c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 8031212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 8131212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @deprecated Replaced by {@link #hasReferences()}. 8231212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 8331212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public boolean hasChildren(); 8488c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 8531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 8631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Does this marker have any references? 8731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 8831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @return true if this marker has one or more references, false otherwise. 8931212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 9031212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public boolean hasReferences(); 9188c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 9231212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 9331212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Returns an Iterator which can be used to iterate over the references of this 9431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * marker. An empty iterator is returned when this marker has no references. 9531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 9631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @return Iterator over the references of this marker 9731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 9831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public Iterator<Marker> iterator(); 9988c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 10031212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 10131212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Does this marker contain a reference to the 'other' marker? Marker A is defined 10231212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * to contain marker B, if A == B or if B is referenced by A, or if B is referenced 10331212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * by any one of A's references (recursively). 10431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 10531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @param other 10631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * The marker to test for inclusion. 10731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @throws IllegalArgumentException 10831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * if 'other' is null 10931212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @return Whether this marker contains the other marker. 11031212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 11131212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public boolean contains(Marker other); 11288c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 11331212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 11431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Does this marker contain the marker named 'name'? 11531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 11631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * If 'name' is null the returned value is always false. 11731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 11831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @param name The marker name to test for inclusion. 11931212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @return Whether this marker contains the other marker. 12031212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 12131212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public boolean contains(String name); 12231212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu 12331212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 12431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Markers are considered equal if they have the same name. 12531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 12631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @param o 12731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @return true, if this.name equals o.name 12831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 12931212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @since 1.5.1 13031212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 13131212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public boolean equals(Object o); 13231212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu 13331212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu /** 13431212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Compute the hash code based on the name of this marker. 13531212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * Note that markers are considered equal if they have the same name. 13631212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * 13731212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @return the computed hashCode 13831212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu * @since 1.5.1 13931212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu */ 14031212435723e2dfd5d6716d1f6a7b0e66a1e6b38Ceki Gulcu public int hashCode(); 14188c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu 14288c4c456766193e012eb890e2208473d99b91f83Ceki Gulcu} 143