001: /*
002: * Copyright (c) 2004-2007 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:
025: package org.slf4j;
026:
027: import java.io.Serializable;
028: import java.util.Iterator;
029:
030: /**
031: * Markers are named objects used to enrich log statements. Conforming
032: * logging system Implementations of SLF4J determine how information
033: * conveyed by markers are used, if at all. In particular, many
034: * conforming logging systems ignore marker data.
035: *
036: * <p>Markers can contain child markers, which in turn can contain children
037: * of their own.
038: *
039: * @author Ceki Gülcü
040: */
041: public interface Marker extends Serializable {
042:
043: /**
044: * This constant represents any marker, including a null marker.
045: */
046: public static final String ANY_MARKER = "*";
047:
048: /**
049: * This constant represents any non-null marker.
050: */
051: public static final String ANY_NON_NULL_MARKER = "+";
052:
053: /**
054: * Get the name of this Marker.
055: * @return name of marker
056: */
057: public String getName();
058:
059: /**
060: * Add a child Marker to this Marker.
061: * @param child a child marker
062: */
063: public void add(Marker child);
064:
065: /**
066: * Remove a child Marker.
067: * @param child the child Marker to remove
068: * @return true if child could be found and removed, false otherwise.
069: */
070: public boolean remove(Marker child);
071:
072: /**
073: * Does this marker have children?
074: * @return true if this marker has children, false otherwise.
075: */
076: public boolean hasChildren();
077:
078: /**
079: * Returns an Iterator which can be used to iterate over the
080: * children of this marker. An empty iterator is returned when this
081: * marker has no children.
082: *
083: * @return Iterator over the children of this marker
084: */
085: public Iterator iterator();
086:
087: /**
088: * Does this marker contain the 'other' marker? Marker A is defined to
089: * contain marker B, if A == B or if B is a child of A.
090: *
091: * @param other The marker to test for inclusion.
092: * @throws IllegalArgumentException if 'other' is null
093: * @return Whether this marker contains the other marker.
094: */
095: public boolean contains(Marker other);
096:
097: /**
098: * Does this marker contain the marker named 'name'?
099: *
100: * If 'name' is null the returned value is always false.
101: *
102: * @param other The marker to test for inclusion.
103: * @return Whether this marker contains the other marker.
104: */
105: public boolean contains(String name);
106:
107: // void makeImmutable();
108: // public boolean isImmutable();
109: }
|