001 /*
002 * Copyright (c) OSGi Alliance (2000, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.log;
017
018 import java.util.Enumeration;
019
020 /**
021 * Provides methods to retrieve <code>LogEntry</code> objects from the log.
022 * <p>
023 * There are two ways to retrieve <code>LogEntry</code> objects:
024 * <ul>
025 * <li>The primary way to retrieve <code>LogEntry</code> objects is to register a
026 * <code>LogListener</code> object whose <code>LogListener.logged</code> method will
027 * be called for each entry added to the log.
028 * <li>To retrieve past <code>LogEntry</code> objects, the <code>getLog</code>
029 * method can be called which will return an <code>Enumeration</code> of all
030 * <code>LogEntry</code> objects in the log.
031 *
032 * @ThreadSafe
033 * @version $Revision: 5654 $
034 * @see LogEntry
035 * @see LogListener
036 * @see LogListener#logged(LogEntry)
037 */
038 public interface LogReaderService {
039 /**
040 * Subscribes to <code>LogEntry</code> objects.
041 *
042 * <p>
043 * This method registers a <code>LogListener</code> object with the Log Reader
044 * Service. The <code>LogListener.logged(LogEntry)</code> method will be
045 * called for each <code>LogEntry</code> object placed into the log.
046 *
047 * <p>
048 * When a bundle which registers a <code>LogListener</code> object is stopped
049 * or otherwise releases the Log Reader Service, the Log Reader Service must
050 * remove all of the bundle's listeners.
051 *
052 * <p>
053 * If this Log Reader Service's list of listeners already contains a
054 * listener <code>l</code> such that <code>(l==listener)</code>, this method
055 * does nothing.
056 *
057 * @param listener A <code>LogListener</code> object to register; the
058 * <code>LogListener</code> object is used to receive <code>LogEntry</code>
059 * objects.
060 * @see LogListener
061 * @see LogEntry
062 * @see LogListener#logged(LogEntry)
063 */
064 public void addLogListener(LogListener listener);
065
066 /**
067 * Unsubscribes to <code>LogEntry</code> objects.
068 *
069 * <p>
070 * This method unregisters a <code>LogListener</code> object from the Log
071 * Reader Service.
072 *
073 * <p>
074 * If <code>listener</code> is not contained in this Log Reader Service's list
075 * of listeners, this method does nothing.
076 *
077 * @param listener A <code>LogListener</code> object to unregister.
078 * @see LogListener
079 */
080 public void removeLogListener(LogListener listener);
081
082 /**
083 * Returns an <code>Enumeration</code> of all <code>LogEntry</code> objects in
084 * the log.
085 *
086 * <p>
087 * Each element of the enumeration is a <code>LogEntry</code> object, ordered
088 * with the most recent entry first. Whether the enumeration is of all
089 * <code>LogEntry</code> objects since the Log Service was started or some
090 * recent past is implementation-specific. Also implementation-specific is
091 * whether informational and debug <code>LogEntry</code> objects are included
092 * in the enumeration.
093 * @return An <code>Enumeration</code> of all <code>LogEntry</code> objects in
094 * the log.
095 */
096 public Enumeration getLog();
097 }