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 org.osgi.framework.ServiceReference;
019
020 /**
021 * Provides methods for bundles to write messages to the log.
022 *
023 * <p>
024 * <code>LogService</code> methods are provided to log messages; optionally with a
025 * <code>ServiceReference</code> object or an exception.
026 *
027 * <p>
028 * Bundles must log messages in the OSGi environment with a severity level
029 * according to the following hierarchy:
030 * <ol>
031 * <li>{@link #LOG_ERROR}
032 * <li>{@link #LOG_WARNING}
033 * <li>{@link #LOG_INFO}
034 * <li>{@link #LOG_DEBUG}
035 * </ol>
036 *
037 * @ThreadSafe
038 * @version $Revision: 5654 $
039 */
040 public interface LogService {
041 /**
042 * An error message (Value 1).
043 *
044 * <p>
045 * This log entry indicates the bundle or service may not be functional.
046 */
047 public static final int LOG_ERROR = 1;
048 /**
049 * A warning message (Value 2).
050 *
051 * <p>
052 * This log entry indicates a bundle or service is still functioning but may
053 * experience problems in the future because of the warning condition.
054 */
055 public static final int LOG_WARNING = 2;
056 /**
057 * An informational message (Value 3).
058 *
059 * <p>
060 * This log entry may be the result of any change in the bundle or service
061 * and does not indicate a problem.
062 */
063 public static final int LOG_INFO = 3;
064 /**
065 * A debugging message (Value 4).
066 *
067 * <p>
068 * This log entry is used for problem determination and may be irrelevant to
069 * anyone but the bundle developer.
070 */
071 public static final int LOG_DEBUG = 4;
072
073 /**
074 * Logs a message.
075 *
076 * <p>
077 * The <code>ServiceReference</code> field and the <code>Throwable</code> field
078 * of the <code>LogEntry</code> object will be set to <code>null</code>.
079 *
080 * @param level The severity of the message. This should be one of the
081 * defined log levels but may be any integer that is interpreted in a
082 * user defined way.
083 * @param message Human readable string describing the condition or
084 * <code>null</code>.
085 * @see #LOG_ERROR
086 * @see #LOG_WARNING
087 * @see #LOG_INFO
088 * @see #LOG_DEBUG
089 */
090 public void log(int level, String message);
091
092 /**
093 * Logs a message with an exception.
094 *
095 * <p>
096 * The <code>ServiceReference</code> field of the <code>LogEntry</code> object
097 * will be set to <code>null</code>.
098 *
099 * @param level The severity of the message. This should be one of the
100 * defined log levels but may be any integer that is interpreted in a
101 * user defined way.
102 * @param message The human readable string describing the condition or
103 * <code>null</code>.
104 * @param exception The exception that reflects the condition or
105 * <code>null</code>.
106 * @see #LOG_ERROR
107 * @see #LOG_WARNING
108 * @see #LOG_INFO
109 * @see #LOG_DEBUG
110 */
111 public void log(int level, String message, Throwable exception);
112
113 /**
114 * Logs a message associated with a specific <code>ServiceReference</code>
115 * object.
116 *
117 * <p>
118 * The <code>Throwable</code> field of the <code>LogEntry</code> will be set to
119 * <code>null</code>.
120 *
121 * @param sr The <code>ServiceReference</code> object of the service that this
122 * message is associated with or <code>null</code>.
123 * @param level The severity of the message. This should be one of the
124 * defined log levels but may be any integer that is interpreted in a
125 * user defined way.
126 * @param message Human readable string describing the condition or
127 * <code>null</code>.
128 * @see #LOG_ERROR
129 * @see #LOG_WARNING
130 * @see #LOG_INFO
131 * @see #LOG_DEBUG
132 */
133 public void log(ServiceReference sr, int level, String message);
134
135 /**
136 * Logs a message with an exception associated and a
137 * <code>ServiceReference</code> object.
138 *
139 * @param sr The <code>ServiceReference</code> object of the service that this
140 * message is associated with.
141 * @param level The severity of the message. This should be one of the
142 * defined log levels but may be any integer that is interpreted in a
143 * user defined way.
144 * @param message Human readable string describing the condition or
145 * <code>null</code>.
146 * @param exception The exception that reflects the condition or
147 * <code>null</code>.
148 * @see #LOG_ERROR
149 * @see #LOG_WARNING
150 * @see #LOG_INFO
151 * @see #LOG_DEBUG
152 */
153 public void log(ServiceReference sr, int level, String message,
154 Throwable exception);
155 }