diff options
author | Thomas Watson | 2017-03-31 14:47:31 +0000 |
---|---|---|
committer | Thomas Watson | 2017-06-16 12:38:08 +0000 |
commit | 1bc1071713d4d94f1c7200fe1a90f806256b7554 (patch) | |
tree | 3a341b5a920b5e4d72462c7f3c914815e346c5ee /bundles/org.eclipse.osgi/osgi/src/org/osgi/service | |
parent | 7b23ce8d04850e284d6c690671a02ea3c5df7655 (diff) | |
download | rt.equinox.framework-1bc1071713d4d94f1c7200fe1a90f806256b7554.tar.gz rt.equinox.framework-1bc1071713d4d94f1c7200fe1a90f806256b7554.tar.xz rt.equinox.framework-1bc1071713d4d94f1c7200fe1a90f806256b7554.zip |
[bug 486950] [osgi R7] log service is being updated
Initial implementation. Includes Java 6/7 aspects only (e.g., no LogStream, etc.).
Diffstat (limited to 'bundles/org.eclipse.osgi/osgi/src/org/osgi/service')
10 files changed, 666 insertions, 146 deletions
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/FormatterLogger.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/FormatterLogger.java new file mode 100644 index 000000000..964972b75 --- /dev/null +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/FormatterLogger.java @@ -0,0 +1,55 @@ +/* + * Copyright (c) OSGi Alliance (2016). All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.osgi.service.log; + +import org.osgi.annotation.versioning.ProviderType; + +/** + * Provides methods for bundles to write messages to the log using printf-style + * format strings. + * <p> + * Messages can be formatted by the Logger once the Logger determines the log + * level is enabled. Uses printf-style format strings as described in + * {@link java.util.Formatter}. + * <p> + * You can also add a {@code Throwable} and/or {@code ServiceReference} to the + * generated {@link LogEntry} by passing them to the logging methods as + * additional arguments. If the last argument is a {@code Throwable} or + * {@code ServiceReference}, it is added to the generated {@link LogEntry} and + * then if the next to last argument is a {@code ServiceReference} or + * {@code Throwable}, it is added to the generated {@link LogEntry}. For + * example: + * + * <pre> + * logger.info("Found service %s.", serviceReference, serviceReference); + * logger.warn("Something named %s happened.", name, serviceReference, + * throwable); + * logger.error("Failed.", exception); + * </pre> + * <p> + * If an exception occurs formatting the message, the logged message will + * indicate the formatting failure including the format string and the + * arguments. + * + * @ThreadSafe + * @author $Id$ + * @since 1.4 + */ +@ProviderType +public interface FormatterLogger extends Logger { + // no additional methods +} diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogEntry.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogEntry.java index 1a6c322e6..1b252eb63 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogEntry.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogEntry.java @@ -1,5 +1,5 @@ /* - * Copyright (c) OSGi Alliance (2000, 2013). All Rights Reserved. + * Copyright (c) OSGi Alliance (2000, 2016). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,6 +16,7 @@ package org.osgi.service.log; +import org.osgi.annotation.versioning.ProviderType; import org.osgi.framework.Bundle; import org.osgi.framework.ServiceReference; @@ -29,11 +30,9 @@ import org.osgi.framework.ServiceReference; * {@code LogListener} object. * * @ThreadSafe - * @noimplement * @author $Id$ - * @see LogReaderService#getLog - * @see LogListener */ +@ProviderType public interface LogEntry { /** * Returns the bundle that created this {@code LogEntry} object. @@ -42,7 +41,7 @@ public interface LogEntry { * {@code null} if no bundle is associated with this * {@code LogEntry} object. */ - public Bundle getBundle(); + Bundle getBundle(); /** * Returns the {@code ServiceReference} object for the service associated @@ -52,23 +51,19 @@ public interface LogEntry { * this {@code LogEntry} object; {@code null} if no * {@code ServiceReference} object was provided. */ - public ServiceReference getServiceReference(); + ServiceReference< ? > getServiceReference(); /** - * Returns the severity level of this {@code LogEntry} object. - * + * Returns the level of this {@code LogEntry} object. * <p> * This is one of the severity levels defined by the {@code LogService} * interface. * - * @return Severity level of this {@code LogEntry} object. - * - * @see LogService#LOG_ERROR - * @see LogService#LOG_WARNING - * @see LogService#LOG_INFO - * @see LogService#LOG_DEBUG + * @return Level of this {@code LogEntry} object. + * @deprecated Since 1.4. Replaced by {@link #getLogLevel()}. */ - public int getLevel(); + @Deprecated + int getLevel(); /** * Returns the human readable message associated with this {@code LogEntry} @@ -77,7 +72,7 @@ public interface LogEntry { * @return {@code String} containing the message associated with this * {@code LogEntry} object. */ - public String getMessage(); + String getMessage(); /** * Returns the exception object associated with this {@code LogEntry} @@ -96,7 +91,7 @@ public interface LogEntry { * {@code LogEntry};{@code null} if no exception is associated with * this {@code LogEntry} object. */ - public Throwable getException(); + Throwable getException(); /** * Returns the value of {@code currentTimeMillis()} at the time this @@ -106,5 +101,60 @@ public interface LogEntry { * was created. * @see "System.currentTimeMillis()" */ - public long getTime(); + long getTime(); + + /** + * Returns the level of this {@code LogEntry} object. + * + * @return The level of this {@code LogEntry} object. + * @since 1.4 + */ + LogLevel getLogLevel(); + + /** + * Returns the name of the {@link Logger} object used to create this + * {@code LogEntry} object. + * + * @return The name of the {@link Logger} object used to create this + * {@code LogEntry} object or {@code ""} if this {@code LogEntry} + * object was created using one of the original {@code LogService} + * {@code log} methods. + * @since 1.4 + */ + String getLoggerName(); + + /** + * Returns the sequence number for this {@code LogEntry} object. + * <p> + * The {@code LogService} assigns a unique, non-negative value that is + * larger than all previously assigned values since the {@code LogService} + * was started. These values are transient and are reused upon restart of + * the {@code LogService}. + * + * @return The sequence number for this {@code LogEntry} object. + * @since 1.4 + */ + long getSequence(); + + /** + * Returns a string representing the thread which created this + * {@code LogEntry} object. + * <p> + * This string contains the name of the thread. + * + * @return A string representing the thread which created this + * {@code LogEntry} object. + * @since 1.4 + */ + String getThreadInfo(); + + /** + * Returns the location information of the creation of this {@code LogEntry} + * object. + * + * @return The location information of the creation of this {@code LogEntry} + * object. + * @since 1.4 + */ + StackTraceElement getLocation(); } diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogLevel.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogLevel.java new file mode 100644 index 000000000..94053969d --- /dev/null +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogLevel.java @@ -0,0 +1,66 @@ +/* + * Copyright (c) OSGi Alliance (2016). All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.osgi.service.log; + +/** + * Log Levels. + * + * @since 1.4 + * @author $Id$ + */ +public enum LogLevel { + /* + * The ordering of the elements is deliberate and must be kept. See {@link + * #implies(LogLevel)}. + */ + /** + * Audit – Information that must always be logged. + */ + AUDIT, + /** + * Error – Information about an error situation. + */ + ERROR, + /** + * Warning – Information about a failure or unwanted situation that is not + * blocking. + */ + WARN, + /** + * Info – Information about normal operation. + */ + INFO, + /** + * Debug – Detailed output for debugging operations. + */ + DEBUG, + /** + * Trace level – Large volume of output for tracing operations. + */ + TRACE; + + /** + * Returns whether this log level implies the specified log level. + * + * @param other The other log level. + * @return {@code true} If this log level implies the specified log level; + * {@code false} otherwise. + */ + public boolean implies(LogLevel other) { + return ordinal() <= other.ordinal(); + } +} diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogListener.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogListener.java index 4e27a9415..49bb6b7e4 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogListener.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogListener.java @@ -1,5 +1,5 @@ /* - * Copyright (c) OSGi Alliance (2000, 2013). All Rights Reserved. + * Copyright (c) OSGi Alliance (2000, 2016). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -18,9 +18,10 @@ package org.osgi.service.log; import java.util.EventListener; +import org.osgi.annotation.versioning.ConsumerType; + /** * Subscribes to {@code LogEntry} objects from the {@code LogReaderService}. - * * <p> * A {@code LogListener} object may be registered with the Log Reader Service * using the {@code LogReaderService.addLogListener} method. After the listener @@ -28,24 +29,19 @@ import java.util.EventListener; * {@code LogEntry} object created. The {@code LogListener} object may be * unregistered by calling the {@code LogReaderService.removeLogListener} * method. + * <p> + * Since 1.4, {@link org.osgi.service.log.stream.LogStream} is the preferred way + * to obtain {@link LogEntry} objects. * * @ThreadSafe * @author $Id$ - * @see LogReaderService - * @see LogEntry - * @see LogReaderService#addLogListener(LogListener) - * @see LogReaderService#removeLogListener(LogListener) */ +@ConsumerType public interface LogListener extends EventListener { /** * Listener method called for each LogEntry object created. * - * <p> - * As with all event listeners, this method should return to its caller as - * soon as possible. - * - * @param entry A {@code LogEntry} object containing log information. - * @see LogEntry + * @param entry A {@link LogEntry} object containing log information. */ - public void logged(LogEntry entry); + void logged(LogEntry entry); } diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogReaderService.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogReaderService.java index ecc3958bd..d61e5de33 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogReaderService.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogReaderService.java @@ -1,5 +1,5 @@ /* - * Copyright (c) OSGi Alliance (2000, 2013). All Rights Reserved. + * Copyright (c) OSGi Alliance (2000, 2016). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -18,83 +18,78 @@ package org.osgi.service.log; import java.util.Enumeration; +import org.osgi.annotation.versioning.ProviderType; + /** - * Provides methods to retrieve {@code LogEntry} objects from the log. + * LogReaderService for obtaining logging information. * <p> - * There are two ways to retrieve {@code LogEntry} objects: + * There are two ways to obtain {@link LogEntry} objects: * <ul> - * <li>The primary way to retrieve {@code LogEntry} objects is to register a - * {@code LogListener} object whose {@code LogListener.logged} method will be - * called for each entry added to the log.</li> - * <li>To retrieve past {@code LogEntry} objects, the {@code getLog} method can - * be called which will return an {@code Enumeration} of all {@code LogEntry} + * <li>The primary way to obtain {@link LogEntry} objects is to get a + * {@link org.osgi.service.log.stream.LogStream} object from the service + * registry. This replaces adding a {@link LogListener} object.</li> + * <li>To obtain past {@link LogEntry} objects, the {@link #getLog()} method can + * be called which will return an {@code Enumeration} of the {@link LogEntry} * objects in the log.</li> * </ul> * * @ThreadSafe * @author $Id$ - * @see LogEntry - * @see LogListener - * @see LogListener#logged(LogEntry) */ +@ProviderType public interface LogReaderService { /** - * Subscribes to {@code LogEntry} objects. - * + * Subscribes to {@link LogEntry} objects. * <p> - * This method registers a {@code LogListener} object with the Log Reader - * Service. The {@code LogListener.logged(LogEntry)} method will be called - * for each {@code LogEntry} object placed into the log. - * + * This method registers a {@link LogListener} object with the Log Reader + * Service. The {@link LogListener#logged(LogEntry)} method will be called + * for each {@link LogEntry} object placed into the log. * <p> - * When a bundle which registers a {@code LogListener} object is stopped or + * When a bundle which registers a {@link LogListener} object is stopped or * otherwise releases the Log Reader Service, the Log Reader Service must * remove all of the bundle's listeners. - * * <p> * If this Log Reader Service's list of listeners already contains a * listener {@code l} such that {@code (l==listener)}, this method does * nothing. + * <p> + * Since 1.4, {@link org.osgi.service.log.stream.LogStream} is the preferred + * way to obtain {@link LogEntry} objects. * - * @param listener A {@code LogListener} object to register; the - * {@code LogListener} object is used to receive {@code LogEntry} - * objects. - * @see LogListener - * @see LogEntry - * @see LogListener#logged(LogEntry) + * @param listener A {@link LogListener} object to register; the + * {@link LogListener} object is used to receive {@link LogEntry} + * objects. */ - public void addLogListener(LogListener listener); + void addLogListener(LogListener listener); /** - * Unsubscribes to {@code LogEntry} objects. - * + * Unsubscribes to {@link LogEntry} objects. * <p> - * This method unregisters a {@code LogListener} object from the Log Reader + * This method unregisters a {@link LogListener} object from the Log Reader * Service. - * * <p> * If {@code listener} is not contained in this Log Reader Service's list of * listeners, this method does nothing. + * <p> + * Since 1.4, {@link org.osgi.service.log.stream.LogStream} is the preferred + * way to obtain {@link LogEntry} objects. * - * @param listener A {@code LogListener} object to unregister. - * @see LogListener + * @param listener A {@link LogListener} object to unregister. */ - public void removeLogListener(LogListener listener); + void removeLogListener(LogListener listener); /** - * Returns an {@code Enumeration} of all {@code LogEntry} objects in the + * Returns an {@code Enumeration} of the {@link LogEntry} objects in the * log. - * * <p> - * Each element of the enumeration is a {@code LogEntry} object, ordered + * Each element of the enumeration is a {@link LogEntry} object, ordered * with the most recent entry first. Whether the enumeration is of all - * {@code LogEntry} objects since the Log Service was started or some recent - * past is implementation-specific. Also implementation-specific is whether - * informational and debug {@code LogEntry} objects are included in the - * enumeration. + * {@link LogEntry} objects since the Log Service was started or some recent + * past is implementation-specific. Also implementation-specific is which + * level {@link LogEntry} objects are included in the enumeration. * - * @return An {@code Enumeration} of all {@code LogEntry} objects in the + * @return An {@code Enumeration} of the {@link LogEntry} objects in the * log. */ - public Enumeration getLog(); + Enumeration<LogEntry> getLog(); } diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogService.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogService.java index dc7a9f634..983c2b524 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogService.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LogService.java @@ -1,5 +1,5 @@ /* - * Copyright (c) OSGi Alliance (2000, 2013). All Rights Reserved. + * Copyright (c) OSGi Alliance (2000, 2016). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,141 +16,132 @@ package org.osgi.service.log; +import org.osgi.annotation.versioning.ProviderType; import org.osgi.framework.ServiceReference; /** - * Provides methods for bundles to write messages to the log. - * - * <p> - * {@code LogService} methods are provided to log messages; optionally with a - * {@code ServiceReference} object or an exception. - * + * LogService for logging information. * <p> - * Bundles must log messages in the OSGi environment with a severity level - * according to the following hierarchy: - * <ol> - * <li>{@link #LOG_ERROR}</li> - * <li>{@link #LOG_WARNING}</li> - * <li>{@link #LOG_INFO}</li> - * <li>{@link #LOG_DEBUG}</li> - * </ol> + * Replaced by {@link LoggerFactory}. * * @ThreadSafe - * @noimplement * @author $Id$ */ -public interface LogService { +@ProviderType +public interface LogService extends LoggerFactory { /** * An error message (Value 1). - * * <p> * This log entry indicates the bundle or service may not be functional. + * + * @deprecated Since 1.4. Replaced by {@link LogLevel#ERROR}. */ - public static final int LOG_ERROR = 1; + @Deprecated + int LOG_ERROR = 1; /** * A warning message (Value 2). - * * <p> * This log entry indicates a bundle or service is still functioning but may * experience problems in the future because of the warning condition. + * + * @deprecated Since 1.4. Replaced by {@link LogLevel#WARN}. */ - public static final int LOG_WARNING = 2; + @Deprecated + int LOG_WARNING = 2; /** * An informational message (Value 3). - * * <p> * This log entry may be the result of any change in the bundle or service * and does not indicate a problem. + * + * @deprecated Since 1.4. Replaced by {@link LogLevel#INFO}. */ - public static final int LOG_INFO = 3; + @Deprecated + int LOG_INFO = 3; /** * A debugging message (Value 4). - * * <p> * This log entry is used for problem determination and may be irrelevant to * anyone but the bundle developer. + * + * @deprecated Since 1.4. Replaced by {@link LogLevel#DEBUG}. */ - public static final int LOG_DEBUG = 4; + @Deprecated + int LOG_DEBUG = 4; /** * Logs a message. - * * <p> * The {@code ServiceReference} field and the {@code Throwable} field of the * {@code LogEntry} object will be set to {@code null}. * * @param level The severity of the message. This should be one of the - * defined log levels but may be any integer that is interpreted in a - * user defined way. + * defined log levels but may be any integer that is interpreted + * in a user defined way. * @param message Human readable string describing the condition or - * {@code null}. - * @see #LOG_ERROR - * @see #LOG_WARNING - * @see #LOG_INFO - * @see #LOG_DEBUG + * {@code null}. + * @deprecated Since 1.4. Replaced by {@link Logger}. See + * {@link LoggerFactory}. */ - public void log(int level, String message); + @Deprecated + void log(int level, String message); /** * Logs a message with an exception. - * * <p> * The {@code ServiceReference} field of the {@code LogEntry} object will be * set to {@code null}. * * @param level The severity of the message. This should be one of the - * defined log levels but may be any integer that is interpreted in a - * user defined way. + * defined log levels but may be any integer that is interpreted + * in a user defined way. * @param message The human readable string describing the condition or - * {@code null}. + * {@code null}. * @param exception The exception that reflects the condition or - * {@code null}. - * @see #LOG_ERROR - * @see #LOG_WARNING - * @see #LOG_INFO - * @see #LOG_DEBUG + * {@code null}. + * @deprecated Since 1.4. Replaced by {@link Logger}. See + * {@link LoggerFactory}. */ - public void log(int level, String message, Throwable exception); + @Deprecated + void log(int level, String message, Throwable exception); /** * Logs a message associated with a specific {@code ServiceReference} * object. - * * <p> * The {@code Throwable} field of the {@code LogEntry} will be set to * {@code null}. * * @param sr The {@code ServiceReference} object of the service that this - * message is associated with or {@code null}. + * message is associated with or {@code null}. * @param level The severity of the message. This should be one of the - * defined log levels but may be any integer that is interpreted in a - * user defined way. + * defined log levels but may be any integer that is interpreted + * in a user defined way. * @param message Human readable string describing the condition or - * {@code null}. - * @see #LOG_ERROR - * @see #LOG_WARNING - * @see #LOG_INFO - * @see #LOG_DEBUG + * {@code null}. + * @deprecated Since 1.4. Replaced by {@link Logger}. See + * {@link LoggerFactory}. */ - public void log(ServiceReference sr, int level, String message); + @Deprecated + void log(ServiceReference< ? > sr, int level, String message); /** * Logs a message with an exception associated and a * {@code ServiceReference} object. * * @param sr The {@code ServiceReference} object of the service that this - * message is associated with. + * message is associated with. * @param level The severity of the message. This should be one of the - * defined log levels but may be any integer that is interpreted in a - * user defined way. + * defined log levels but may be any integer that is interpreted + * in a user defined way. * @param message Human readable string describing the condition or - * {@code null}. + * {@code null}. * @param exception The exception that reflects the condition or - * {@code null}. - * @see #LOG_ERROR - * @see #LOG_WARNING - * @see #LOG_INFO - * @see #LOG_DEBUG + * {@code null}. + * @deprecated Since 1.4. Replaced by {@link Logger}. See + * {@link LoggerFactory}. */ - public void log(ServiceReference sr, int level, String message, Throwable exception); + @Deprecated + void log(ServiceReference< ? > sr, int level, String message, + Throwable exception); } diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/Logger.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/Logger.java new file mode 100644 index 000000000..564a0ad19 --- /dev/null +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/Logger.java @@ -0,0 +1,292 @@ +/* + * Copyright (c) OSGi Alliance (2016). All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.osgi.service.log; + +import org.osgi.annotation.versioning.ProviderType; + +/** + * Provides methods for bundles to write messages to the log using SLF4J-style + * format strings. + * <p> + * Messages can be formatted by the Logger once the Logger determines the log + * level is enabled. Use <code>"{}"</code> as a place holder for an argument. If + * you need to use the literal <code>"{}"</code> in the formatted message, + * precede the place holder with a backslash: <code>"\\{}"</code>. If you need + * to place a backslash before the place holder, precede the backslash with a + * backslash: <code>"\\\\{}"</code>. + * <p> + * You can also add a {@code Throwable} and/or {@code ServiceReference} to the + * generated {@link LogEntry} by passing them to the logging methods as + * additional arguments. If the last argument is a {@code Throwable} or + * {@code ServiceReference}, it is added to the generated {@link LogEntry} and + * then if the next to last argument is a {@code ServiceReference} or + * {@code Throwable}, it is added to the generated {@link LogEntry}. These + * arguments will not be used for place holders. For example: + * + * <pre> + * logger.info("Found service {}.", serviceReference, serviceReference); + * logger.warn("Something named {} happened.", name, serviceReference, + * throwable); + * logger.error("Failed.", exception); + * </pre> + * + * @ThreadSafe + * @author $Id$ + * @since 1.4 + */ +@ProviderType +public interface Logger { + + /** + * Return the name of this Logger. + * + * @return The name of this Logger. + */ + String getName(); + + /** + * Is logging enabled for the {@link LogLevel#TRACE} level? + * + * @return {@code true} if logging is enabled for the {@link LogLevel#TRACE} + * level. + */ + boolean isTraceEnabled(); + + /** + * Log a message at the {@link LogLevel#TRACE} level. + * + * @param message The message to log. + */ + void trace(String message); + + /** + * Log a formatted message at the {@link LogLevel#TRACE} level. + * + * @param format The format of the message to log. + * @param arg The argument to format into the message. + */ + void trace(String format, Object arg); + + /** + * Log a formatted message at the {@link LogLevel#TRACE} level. + * + * @param format The format of the message to log. + * @param arg1 The first argument to format into the message. + * @param arg2 The second argument to format into the message. + */ + void trace(String format, Object arg1, Object arg2); + + /** + * Log a formatted message at the {@link LogLevel#TRACE} level. + * + * @param format The format of the message to log. + * @param arguments The arguments to format into the message. + */ + void trace(String format, Object... arguments); + + /** + * Is logging enabled for the {@link LogLevel#DEBUG} level? + * + * @return {@code true} if logging is enabled for the {@link LogLevel#DEBUG + * trace} level. + */ + boolean isDebugEnabled(); + + /** + * Log a message at the {@link LogLevel#DEBUG} level. + * + * @param message The message to log. + */ + void debug(String message); + + /** + * Log a formatted message at the {@link LogLevel#DEBUG} level. + * + * @param format The format of the message to log. + * @param arg The argument to format into the message. + */ + void debug(String format, Object arg); + + /** + * Log a formatted message at the {@link LogLevel#DEBUG} level. + * + * @param format The format of the message to log. + * @param arg1 The first argument to format into the message. + * @param arg2 The second argument to format into the message. + */ + void debug(String format, Object arg1, Object arg2); + + /** + * Log a formatted message at the {@link LogLevel#DEBUG} level. + * + * @param format The format of the message to log. + * @param arguments The arguments to format into the message. + */ + void debug(String format, Object... arguments); + + /** + * Is logging enabled for the {@link LogLevel#INFO} level? + * + * @return {@code true} if logging is enabled for the {@link LogLevel#INFO + * trace} level. + */ + boolean isInfoEnabled(); + + /** + * Log a message at the {@link LogLevel#INFO} level. + * + * @param message The message to log. + */ + void info(String message); + + /** + * Log a formatted message at the {@link LogLevel#INFO} level. + * + * @param format The format of the message to log. + * @param arg The argument to format into the message. + */ + void info(String format, Object arg); + + /** + * Log a formatted message at the {@link LogLevel#INFO} level. + * + * @param format The format of the message to log. + * @param arg1 The first argument to format into the message. + * @param arg2 The second argument to format into the message. + */ + void info(String format, Object arg1, Object arg2); + + /** + * Log a formatted message at the {@link LogLevel#INFO} level. + * + * @param format The format of the message to log. + * @param arguments The arguments to format into the message. + */ + void info(String format, Object... arguments); + + /** + * Is logging enabled for the {@link LogLevel#WARN} level? + * + * @return {@code true} if logging is enabled for the {@link LogLevel#WARN + * trace} level. + */ + boolean isWarnEnabled(); + + /** + * Log a message at the {@link LogLevel#WARN} level. + * + * @param message The message to log. + */ + void warn(String message); + + /** + * Log a formatted message at the {@link LogLevel#WARN} level. + * + * @param format The format of the message to log. + * @param arg The argument to format into the message. + */ + void warn(String format, Object arg); + + /** + * Log a formatted message at the {@link LogLevel#WARN} level. + * + * @param format The format of the message to log. + * @param arg1 The first argument to format into the message. + * @param arg2 The second argument to format into the message. + */ + void warn(String format, Object arg1, Object arg2); + + /** + * Log a formatted message at the {@link LogLevel#WARN} level. + * + * @param format The format of the message to log. + * @param arguments The arguments to format into the message. + */ + void warn(String format, Object... arguments); + + /** + * Is logging enabled for the {@link LogLevel#ERROR} level? + * + * @return {@code true} if logging is enabled for the {@link LogLevel#ERROR + * trace} level. + */ + boolean isErrorEnabled(); + + /** + * Log a message at the {@link LogLevel#ERROR} level. + * + * @param message The message to log. + */ + void error(String message); + + /** + * Log a formatted message at the {@link LogLevel#ERROR} level. + * + * @param format The format of the message to log. + * @param arg The argument to format into the message. + */ + void error(String format, Object arg); + + /** + * Log a formatted message at the {@link LogLevel#ERROR} level. + * + * @param format The format of the message to log. + * @param arg1 The first argument to format into the message. + * @param arg2 The second argument to format into the message. + */ + void error(String format, Object arg1, Object arg2); + + /** + * Log a formatted message at the {@link LogLevel#ERROR} level. + * + * @param format The format of the message to log. + * @param arguments The arguments to format into the message. + */ + void error(String format, Object... arguments); + + /** + * Log a message at the {@link LogLevel#AUDIT} level. + * + * @param message The message to log. + */ + void audit(String message); + + /** + * Log a formatted message at the {@link LogLevel#AUDIT} level. + * + * @param format The format of the message to log. + * @param arg The argument to format into the message. + */ + void audit(String format, Object arg); + + /** + * Log a formatted message at the {@link LogLevel#AUDIT} level. + * + * @param format The format of the message to log. + * @param arg1 The first argument to format into the message. + * @param arg2 The second argument to format into the message. + */ + void audit(String format, Object arg1, Object arg2); + + /** + * Log a formatted message at the {@link LogLevel#AUDIT} level. + * + * @param format The format of the message to log. + * @param arguments The arguments to format into the message. + */ + void audit(String format, Object... arguments); +} diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LoggerFactory.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LoggerFactory.java new file mode 100644 index 000000000..df1835468 --- /dev/null +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/LoggerFactory.java @@ -0,0 +1,77 @@ +/* + * Copyright (c) OSGi Alliance (2016). All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.osgi.service.log; + +import org.osgi.annotation.versioning.ProviderType; + +/** + * Logger Factory service for logging information. + * <p> + * Provides methods for bundles to obtain named {@link Logger}s that can be used + * to write messages to the log. + * + * @ThreadSafe + * @since 1.4 + * @author $Id$ + */ +@ProviderType +public interface LoggerFactory { + + /** + * Return a {@link Logger} named with the specified name. + * + * @param name The name to use for the logger name. + * @return A {@link Logger} named with the specified name. + */ + Logger getLogger(String name); + + /** + * Return a {@link Logger} named with the specified class. + * + * @param clazz The class to use for the logger name. + * @return A {@link Logger} named with the specified class. + */ + Logger getLogger(Class< ? > clazz); + + /** + * Return a {@link Logger} of the specified type named with the specified + * name. + * + * @param <L> A Logger type. + * @param name The name to use for the logger name. + * @param loggerType The type of Logger. Can be {@link Logger} or + * {@link FormatterLogger}. + * @return A {@link Logger} named with the specified name. + * @throws IllegalArgumentException If the specified type is not a supported + * Logger type. + */ + <L extends Logger> L getLogger(String name, Class<L> loggerType); + + /** + * Return a {@link Logger} of the specified type named with the specified + * class. + * + * @param <L> A Logger type. + * @param clazz The class to use for the logger name. + * @param loggerType The type of Logger. Can be {@link Logger} or + * {@link FormatterLogger}. + * @return A {@link Logger} named with the specified class. + * @throws IllegalArgumentException If the specified type is not a supported + * Logger type. + */ + <L extends Logger> L getLogger(Class< ? > clazz, Class<L> loggerType); +} diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/package-info.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/package-info.java index 928099019..81c287aee 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/package-info.java +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) OSGi Alliance (2010, 2012). All Rights Reserved. + * Copyright (c) OSGi Alliance (2010, 2016). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -15,26 +15,24 @@ */ /** - * Log Service Package Version 1.3. - * + * Log Service Package Version 1.4. * <p> * Bundles wishing to use this package must list the package in the * Import-Package header of the bundle's manifest. This package has two types of * users: the consumers that use the API in this package and the providers that * implement the API in this package. - * * <p> * Example import for consumers using the API in this package: * <p> - * {@code Import-Package: org.osgi.service.log; version="[1.3,2.0)"} + * {@code Import-Package: org.osgi.service.log; version="[1.4,2.0)"} * <p> * Example import for providers implementing the API in this package: * <p> - * {@code Import-Package: org.osgi.service.log; version="[1.3,1.4)"} + * {@code Import-Package: org.osgi.service.log; version="[1.4,1.5)"} * - * @version 1.3 * @author $Id$ */ - +@Version("1.4") package org.osgi.service.log; +import org.osgi.annotation.versioning.Version; diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/packageinfo b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/packageinfo index 0117a56c1..cc13f1958 100644 --- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/packageinfo +++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/packageinfo @@ -1 +1 @@ -version 1.3 +version 1.4 |