Update OSGi Log Service API to the latest for R7

3 files changed, 65 insertions, 27 deletions

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
index 790a664f4..22593d316 100644
--- 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
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2016). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2016, 2017). 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.
@@ -54,7 +54,7 @@ public interface Logger {
 	/**
 	 * Root Logger Name.
 	 */
-	static String ROOT_LOGGER_NAME = "ROOT";
+	String ROOT_LOGGER_NAME = "ROOT";
 
 	/**
 	 * Return the name of this Logger.
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/admin/LoggerAdmin.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/admin/LoggerAdmin.java
index 5f68a1c1b..5a3687976 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/admin/LoggerAdmin.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/admin/LoggerAdmin.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2016). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2016, 2017). 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.
@@ -47,8 +47,10 @@ import org.osgi.service.log.LoggerFactory;
  * <symbolic-name>
  * </pre>
  * 
- * If a non-empty Logger Context is not found, the Logger Context with the name
- * {@code <symbolic-name>} is used for the bundle.
+ * The search stops at the first {@link LoggerContext#isEmpty() non-empty}
+ * Logger Context. If no non-empty Logger Context is found using the above
+ * search order, the Logger Context with the symbolic name of the bundle must be
+ * used for the bundle.
  * 
  * @ThreadSafe
  * @author $Id$
@@ -64,14 +66,15 @@ public interface LoggerAdmin {
 	 * <p>
 	 * The value of this service property must be of type {@code Long}.
 	 */
-	static String LOG_SERVICE_ID = "osgi.log.service.id";
+	String LOG_SERVICE_ID = "osgi.log.service.id";
 
 	/**
 	 * Get the Logger Context for the specified name.
 	 * 
 	 * @param name The name of the Logger Context. Can be {@code null} to
 	 *            specify the root Logger Context.
-	 * @return The Logger Context for the specified name.
+	 * @return The Logger Context for the specified name. The returned Logger
+	 *         Context may be {@link LoggerContext#isEmpty() empty}.
 	 */
 	LoggerContext getLoggerContext(String name);
 }
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/admin/LoggerContext.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/admin/LoggerContext.java
index 33b9e4b6f..a5124e0e6 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/admin/LoggerContext.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/service/log/admin/LoggerContext.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) OSGi Alliance (2016). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2016, 2017). 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.
@@ -34,6 +34,38 @@ import org.osgi.service.log.LogLevel;
 @ProviderType
 public interface LoggerContext {
 	/**
+	 * Logger Context PID.
+	 * <p>
+	 * If Configuration Admin is present, Logger Context configuration
+	 * information in Configuration Admin must be used. The name of the Logger
+	 * Context is mapped to a Configuration Admin targeted PID as follows:
+	 * <ul>
+	 * <li>The root Logger Context, which has no name, is mapped to the PID
+	 * {@code org.osgi.service.log.admin}.</li>
+	 * <li>A named Logger Context is mapped to a targeted PID by prefixing the
+	 * Logger Context's name with {@code org.osgi.service.log.admin|}. For
+	 * example, the Logger Context named {@code com.foo.bar} is mapped to the
+	 * targeted PID {@code org.osgi.service.log.admin|com.foo.bar}.</li>
+	 * </ul>
+	 */
+	String LOGGER_CONTEXT_PID = "org.osgi.service.log.admin";
+
+	/**
+	 * Framework launching property specifying the default log level of the root
+	 * Logger Context.
+	 * <p>
+	 * The value of this property must be the name of the one of the
+	 * {@link LogLevel}s.
+	 * <p>
+	 * If not specified, or the specified value is not the name of the one of
+	 * the {@link LogLevel}s, the default log level of the root Logger Context
+	 * is {@link LogLevel#WARN}.
+	 * 
+	 * @see LogLevel
+	 */
+	String	LOGGER_CONTEXT_DEFAULT_LOGLEVEL	= "org.osgi.service.log.admin.loglevel";
+
+	/**
 	 * Returns the name for this Logger Context.
 	 * 
 	 * @return The name for this Logger Context. The root Logger Context has no
@@ -48,19 +80,16 @@ public interface LoggerContext {
 	 * The effective log level for a logger name is found by the following
 	 * steps:
 	 * <ol>
-	 * <li>If the specified logger name is configured with a non-null log level
-	 * in this Logger Context, return the configured log level.</li>
-	 * <li>For each ancestor logger name of the specified logger name, if the
-	 * ancestor logger name is configured with a non-null log level in this
-	 * Logger Context, return the configured log level.</li>
-	 * <li>If the specified logger name is configured with a non-null log level
-	 * in the root Logger Context, return the configured log level.</li>
+	 * <li>If the specified logger name is configured with a log level, return
+	 * the configured log level.</li>
 	 * <li>For each ancestor logger name of the specified logger name, if the
-	 * ancestor logger name is configured with a non-null log level in the root
-	 * Logger Context, return the configured log level.</li>
-	 * <li>Return {@link LogLevel#WARN} because no non-null log level has been
-	 * found for the specified logger name or any of its ancestor logger names.
-	 * </li>
+	 * ancestor logger name is configured with a log level, return the
+	 * configured log level.</li>
+	 * <li>If this Logger Context is named, return the result of calling this
+	 * method on the root Logger Context with the specified logger name.</li>
+	 * <li>If this Logger Context is the root Logger Context, return the
+	 * {@link #LOGGER_CONTEXT_DEFAULT_LOGLEVEL default log level of the root
+	 * Logger Context}.</li>
 	 * </ol>
 	 * 
 	 * @param name The logger name.
@@ -75,10 +104,10 @@ public interface LoggerContext {
 	 * @return The configured log levels for this Logger Context. The keys are
 	 *         the logger names and the values are the log levels. The returned
 	 *         map may be empty if no logger names are configured for this
-	 *         Logger Context. The log level value can be {@code null}. The
-	 *         returned map is the property of the caller who can modify the map
-	 *         and use it as input to {@link #setLogLevels(Map)}. The returned
-	 *         map must support all optional Map operations.
+	 *         Logger Context. The returned map is the property of the caller
+	 *         who can modify the map and use it as input to
+	 *         {@link #setLogLevels(Map)}. The returned map must support all
+	 *         optional Map operations.
 	 */
 	Map<String,LogLevel> getLogLevels();
 
@@ -87,12 +116,18 @@ public interface LoggerContext {
 	 * <p>
 	 * All previous log levels configured for this Logger Context are cleared
 	 * and then the log levels in the specified map are configured.
+	 * <p>
+	 * The configured log levels for this Logger Context can be set by both this
+	 * method and by configuration information in Configuration Admin, if
+	 * Configuration Admin is present. The configured log levels for this Logger
+	 * Context are based upon the last technique used to update the configured
+	 * log levels. This method must not modify or set configuration information
+	 * in Configuration Admin.
 	 * 
 	 * @param logLevels The log levels to configure for this Logger Context. The
 	 *            keys are the logger names and the values are the log levels.
-	 *            The log level value can be {@code null}. The specified map is
-	 *            the property of the caller and this method must not modify or
-	 *            retain the specified map.
+	 *            The specified map is the property of the caller and this
+	 *            method must not modify or retain the specified map.
 	 */
 	void setLogLevels(Map<String,LogLevel> logLevels);