Bug 518515 - Update OSGi APIs for R7
Change-Id: Ib26b500c3283111602199ef6783d6295367c32a8
Signed-off-by: Thomas Watson <tjwatson@us.ibm.com>
diff --git a/bundles/org.eclipse.osgi.services/.settings/.api_filters b/bundles/org.eclipse.osgi.services/.settings/.api_filters
index c92f575..5799d57 100644
--- a/bundles/org.eclipse.osgi.services/.settings/.api_filters
+++ b/bundles/org.eclipse.osgi.services/.settings/.api_filters
@@ -1,185 +1,38 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<component id="org.eclipse.osgi.services" version="2">
- <resource path="src/org/osgi/service/component/ComponentConstants.java" type="org.osgi.service.component.ComponentConstants">
- <filter id="403767336">
- <message_arguments>
- <message_argument value="org.osgi.service.component.ComponentConstants"/>
- <message_argument value="COMPONENT_CAPABILITY_NAME"/>
- </message_arguments>
- </filter>
- <filter id="1209008130">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="COMPONENT_CAPABILITY_NAME"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/ComponentServiceObjects.java" type="org.osgi.service.component.ComponentServiceObjects">
+ <resource path="src/org/osgi/service/log/FormatterLogger.java" type="org.osgi.service.log.FormatterLogger">
<filter id="1108344834">
<message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.ComponentServiceObjects"/>
+ <message_argument value="1.4"/>
+ <message_argument value="3.7"/>
+ <message_argument value="org.osgi.service.log.FormatterLogger"/>
</message_arguments>
</filter>
</resource>
- <resource path="src/org/osgi/service/component/annotations/Component.java" type="org.osgi.service.component.annotations.Component">
- <filter comment="Bug 501950 - [ds] replace Equinox DS implementation with Felix SCR (DS)" id="286326823">
- <message_arguments>
- <message_argument value="org.osgi.service.component.annotations.Component"/>
- <message_argument value="NAME"/>
- </message_arguments>
- </filter>
- <filter id="286375965">
- <message_arguments>
- <message_argument value="org.osgi.service.component.annotations.Component"/>
- <message_argument value="reference()"/>
- </message_arguments>
- </filter>
- <filter id="288469092">
- <message_arguments>
- <message_argument value="org.osgi.service.component.annotations.Component"/>
- <message_argument value="configurationPid()"/>
- </message_arguments>
- </filter>
- <filter id="1091567618">
- <message_arguments>
- <message_argument value="1.2"/>
- <message_argument value="3.6"/>
- <message_argument value="configurationPid()"/>
- </message_arguments>
- </filter>
- <filter id="1091567618">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="NAME"/>
- </message_arguments>
- </filter>
- <filter id="1091567618">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="reference()"/>
- </message_arguments>
- </filter>
- <filter id="1091567618">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="scope()"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/annotations/FieldOption.java" type="org.osgi.service.component.annotations.FieldOption">
+ <resource path="src/org/osgi/service/log/LogLevel.java" type="org.osgi.service.log.LogLevel">
<filter id="1108344834">
<message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.annotations.FieldOption"/>
+ <message_argument value="1.4"/>
+ <message_argument value="3.7"/>
+ <message_argument value="org.osgi.service.log.LogLevel"/>
</message_arguments>
</filter>
</resource>
- <resource path="src/org/osgi/service/component/annotations/Reference.java" type="org.osgi.service.component.annotations.Reference">
- <filter id="1091567618">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="bind()"/>
- </message_arguments>
- </filter>
- <filter id="1091567618">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="field()"/>
- </message_arguments>
- </filter>
- <filter id="1091567618">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="fieldOption()"/>
- </message_arguments>
- </filter>
- <filter id="1091567618">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="scope()"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/annotations/ReferenceScope.java" type="org.osgi.service.component.annotations.ReferenceScope">
+ <resource path="src/org/osgi/service/log/Logger.java" type="org.osgi.service.log.Logger">
<filter id="1108344834">
<message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.annotations.ReferenceScope"/>
+ <message_argument value="1.4"/>
+ <message_argument value="3.7"/>
+ <message_argument value="org.osgi.service.log.Logger"/>
</message_arguments>
</filter>
</resource>
- <resource path="src/org/osgi/service/component/annotations/ServiceScope.java" type="org.osgi.service.component.annotations.ServiceScope">
+ <resource path="src/org/osgi/service/log/LoggerFactory.java" type="org.osgi.service.log.LoggerFactory">
<filter id="1108344834">
<message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.annotations.ServiceScope"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/runtime/ServiceComponentRuntime.java" type="org.osgi.service.component.runtime.ServiceComponentRuntime">
- <filter id="1108344834">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.runtime.ServiceComponentRuntime"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/runtime/dto/ComponentConfigurationDTO.java" type="org.osgi.service.component.runtime.dto.ComponentConfigurationDTO">
- <filter id="1108344834">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.runtime.dto.ComponentConfigurationDTO"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/runtime/dto/ComponentDescriptionDTO.java" type="org.osgi.service.component.runtime.dto.ComponentDescriptionDTO">
- <filter id="1108344834">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.runtime.dto.ComponentDescriptionDTO"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/runtime/dto/ReferenceDTO.java" type="org.osgi.service.component.runtime.dto.ReferenceDTO">
- <filter id="1108344834">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.runtime.dto.ReferenceDTO"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/runtime/dto/SatisfiedReferenceDTO.java" type="org.osgi.service.component.runtime.dto.SatisfiedReferenceDTO">
- <filter id="1108344834">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.runtime.dto.SatisfiedReferenceDTO"/>
- </message_arguments>
- </filter>
- </resource>
- <resource path="src/org/osgi/service/component/runtime/dto/UnsatisfiedReferenceDTO.java" type="org.osgi.service.component.runtime.dto.UnsatisfiedReferenceDTO">
- <filter id="1108344834">
- <message_arguments>
- <message_argument value="1.3"/>
- <message_argument value="3.6"/>
- <message_argument value="org.osgi.service.component.runtime.dto.UnsatisfiedReferenceDTO"/>
+ <message_argument value="1.4"/>
+ <message_argument value="3.7"/>
+ <message_argument value="org.osgi.service.log.LoggerFactory"/>
</message_arguments>
</filter>
</resource>
diff --git a/bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF b/bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF
index 6527349..a14ee70 100644
--- a/bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF
+++ b/bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF
@@ -2,7 +2,7 @@
Bundle-ManifestVersion: 2
Bundle-Name: %osgiServices
Bundle-SymbolicName: org.eclipse.osgi.services
-Bundle-Version: 3.6.0.qualifier
+Bundle-Version: 3.7.0.qualifier
Bundle-Description: %osgiServicesDes
Bundle-Localization: plugin
Bundle-Vendor: %eclipse.org
@@ -20,7 +20,7 @@
org.osgi.service.http.runtime;version="1.0";uses:="org.osgi.service.http.runtime.dto",
org.osgi.service.http.runtime.dto;version="1.0";uses:="org.osgi.dto,org.osgi.framework.dto",
org.osgi.service.http.whiteboard;version="1.0",
- org.osgi.service.log;version="1.3";uses:="org.osgi.framework",
+ org.osgi.service.log;version="1.4";uses:="org.osgi.framework",
org.osgi.service.metatype;version="1.3";uses:="org.osgi.framework",
org.osgi.service.provisioning;version="1.2",
org.osgi.service.upnp;version="1.2",
@@ -39,7 +39,7 @@
org.osgi.service.device;version="[1.1,1.2)",
org.osgi.service.event;version="[1.3,1.4)",
org.osgi.service.http;version="[1.2,1.3)",
- org.osgi.service.log;version="[1.3,1.4)",
+ org.osgi.service.log;version="[1.4,1.5)",
org.osgi.service.metatype;version="[1.3,1.4)",
org.osgi.service.provisioning;version="[1.2,1.3)",
org.osgi.service.upnp;version="[1.2,1.3)",
diff --git a/bundles/org.eclipse.osgi.services/build.properties b/bundles/org.eclipse.osgi.services/build.properties
index 8427ee5..817b7fd 100644
--- a/bundles/org.eclipse.osgi.services/build.properties
+++ b/bundles/org.eclipse.osgi.services/build.properties
@@ -18,4 +18,5 @@
source.. = src/
output.. = bin/
-jars.extra.classpath = lib/osgi.annotation.jar
\ No newline at end of file
+jars.extra.classpath = lib/osgi.annotation.jar,\
+ lib/function.interface.jar
\ No newline at end of file
diff --git a/bundles/org.eclipse.osgi.services/lib/function.interface.jar b/bundles/org.eclipse.osgi.services/lib/function.interface.jar
new file mode 100755
index 0000000..d2f0831
--- /dev/null
+++ b/bundles/org.eclipse.osgi.services/lib/function.interface.jar
Binary files differ
diff --git a/bundles/org.eclipse.osgi.services/pom.xml b/bundles/org.eclipse.osgi.services/pom.xml
index 167274b..64bc940 100644
--- a/bundles/org.eclipse.osgi.services/pom.xml
+++ b/bundles/org.eclipse.osgi.services/pom.xml
@@ -19,7 +19,7 @@
</parent>
<groupId>org.eclipse.osgi</groupId>
<artifactId>org.eclipse.osgi.services</artifactId>
- <version>3.6.0-SNAPSHOT</version>
+ <version>3.7.0-SNAPSHOT</version>
<packaging>eclipse-plugin</packaging>
<build>
<plugins>
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/FormatterLogger.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/FormatterLogger.java
new file mode 100644
index 0000000..5fe2297
--- /dev/null
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/FormatterLogger.java
@@ -0,0 +1,56 @@
+/*
+ * 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.
+ * 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} and not the same type as the last argument, it is also
+ * added to the generated {@link LogEntry}. These arguments will not be used as
+ * message arguments. 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.services/src/org/osgi/service/log/LogEntry.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogEntry.java
index 1a6c322..6b3ee59 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogEntry.java
+++ b/bundles/org.eclipse.osgi.services/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 @@
* {@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 @@
* {@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,21 @@
* 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 integer level of this {@code LogEntry} object.
* <p>
- * This is one of the severity levels defined by the {@code LogService}
- * interface.
+ * If one of the {@code log} methods of {@link LogService} was used, this is
+ * the specified integer level. Otherwise, this is the
+ * {@link LogLevel#ordinal() ordinal} value of the {@link #getLogLevel() log
+ * level}.
*
- * @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 Integer 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 +74,7 @@
* @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 +93,7 @@
* {@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 +103,58 @@
* 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.
+ * @since 1.4
+ */
+ String getLoggerName();
+
+ /**
+ * Returns the sequence number for this {@code LogEntry} object.
+ * <p>
+ * A unique, non-negative value that is larger than all previously assigned
+ * values since the log implementation was started. These values are
+ * transient and are reused upon restart of the log implementation.
+ *
+ * @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 must contain the name of the thread and may contain other
+ * information about 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.services/src/org/osgi/service/log/LogLevel.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogLevel.java
new file mode 100644
index 0000000..ebc1f14
--- /dev/null
+++ b/bundles/org.eclipse.osgi.services/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.services/src/org/osgi/service/log/LogListener.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogListener.java
index 4e27a94..accab42 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogListener.java
+++ b/bundles/org.eclipse.osgi.services/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 @@
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,20 @@
* {@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.LogStreamProvider} 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
+@FunctionalInterface
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.services/src/org/osgi/service/log/LogReaderService.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogReaderService.java
index ecc3958..2e91c2e 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogReaderService.java
+++ b/bundles/org.eclipse.osgi.services/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, 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.
@@ -18,83 +18,80 @@
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:
+ * Since 1.4, {@link org.osgi.service.log.stream.LogStreamProvider} is the
+ * preferred way to obtain {@link LogEntry} objects.
+ * <p>
+ * The LogReaderService provides 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 retrieve {@link LogEntry} objects is to register a
+ * {@link LogListener} object whose {@link LogListener#logged(LogEntry)} method
+ * will be called for each entry added to the log.</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.LogStreamProvider} 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.LogStreamProvider} 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.
*
- * @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.services/src/org/osgi/service/log/LogService.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogService.java
index dc7a9f6..55d1069 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LogService.java
+++ b/bundles/org.eclipse.osgi.services/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,184 @@
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.
- *
+ * LogService for logging information.
* <p>
- * {@code LogService} methods are provided to log messages; optionally with a
- * {@code ServiceReference} object or an exception.
- *
- * <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}.
+ * <p>
+ * This method will log to the {@link Logger} named {@code "LogService"} for
+ * the bundle. The specified level is mapped to a {@link LogLevel} as
+ * follows:
+ * <ul>
+ * <li>{@link #LOG_ERROR} - {@link LogLevel#ERROR}</li>
+ * <li>{@link #LOG_WARNING} - {@link LogLevel#WARN}</li>
+ * <li>{@link #LOG_INFO} - {@link LogLevel#INFO}</li>
+ * <li>{@link #LOG_DEBUG} - {@link LogLevel#DEBUG}</li>
+ * <li>Any other value - {@link LogLevel#TRACE}</li>
+ * </ul>
+ * In the generated log entry, {@link LogEntry#getLevel()} must return the
+ * specified level.
*
* @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}.
+ * <p>
+ * This method will log to the {@link Logger} named {@code "LogService"} for
+ * the bundle. The specified level is mapped to a {@link LogLevel} as
+ * follows:
+ * <ul>
+ * <li>{@link #LOG_ERROR} - {@link LogLevel#ERROR}</li>
+ * <li>{@link #LOG_WARNING} - {@link LogLevel#WARN}</li>
+ * <li>{@link #LOG_INFO} - {@link LogLevel#INFO}</li>
+ * <li>{@link #LOG_DEBUG} - {@link LogLevel#DEBUG}</li>
+ * <li>Any other value - {@link LogLevel#TRACE}</li>
+ * </ul>
+ * In the generated log entry, {@link LogEntry#getLevel()} must return the
+ * specified level.
*
* @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}.
+ * <p>
+ * This method will log to the {@link Logger} named {@code "LogService"} for
+ * the bundle. The specified level is mapped to a {@link LogLevel} as
+ * follows:
+ * <ul>
+ * <li>{@link #LOG_ERROR} - {@link LogLevel#ERROR}</li>
+ * <li>{@link #LOG_WARNING} - {@link LogLevel#WARN}</li>
+ * <li>{@link #LOG_INFO} - {@link LogLevel#INFO}</li>
+ * <li>{@link #LOG_DEBUG} - {@link LogLevel#DEBUG}</li>
+ * <li>Any other value - {@link LogLevel#TRACE}</li>
+ * </ul>
+ * In the generated log entry, {@link LogEntry#getLevel()} must return the
+ * specified level.
*
* @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.
+ * <p>
+ * This method will log to the {@link Logger} named {@code "LogService"} for
+ * the bundle. The specified level is mapped to a {@link LogLevel} as
+ * follows:
+ * <ul>
+ * <li>{@link #LOG_ERROR} - {@link LogLevel#ERROR}</li>
+ * <li>{@link #LOG_WARNING} - {@link LogLevel#WARN}</li>
+ * <li>{@link #LOG_INFO} - {@link LogLevel#INFO}</li>
+ * <li>{@link #LOG_DEBUG} - {@link LogLevel#DEBUG}</li>
+ * <li>Any other value - {@link LogLevel#TRACE}</li>
+ * </ul>
+ * In the generated log entry, {@link LogEntry#getLevel()} must return the
+ * specified level.
*
* @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.services/src/org/osgi/service/log/Logger.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/Logger.java
new file mode 100644
index 0000000..a9cc36a
--- /dev/null
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/Logger.java
@@ -0,0 +1,299 @@
+/*
+ * 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.
+ * 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 a left curly bracket (<code>'{'</code> \u007B)
+ * followed by a right curly bracket (<code>'}'</code> \u007D) as a place
+ * holder for an argument: <code>"{}"</code>. If you need to use the literal
+ * <code>"{}"</code> in the formatted message, precede the place holder with a
+ * reverse solidus ({@code '\'} \u005C): <code>"\{}"</code>. If you need to
+ * place a backslash before the place holder, precede the reverse solidus with a
+ * reverse solidus: <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 a
+ * {@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} and not the same type as the last argument, it is also
+ * added to the generated {@link LogEntry}. These arguments will not be used as
+ * message arguments. 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 {
+ /**
+ * Root Logger Name.
+ */
+ String ROOT_LOGGER_NAME = "ROOT";
+
+ /**
+ * 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.services/src/org/osgi/service/log/LoggerFactory.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LoggerFactory.java
new file mode 100644
index 0000000..61d256f
--- /dev/null
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/LoggerFactory.java
@@ -0,0 +1,129 @@
+/*
+ * 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;
+import org.osgi.framework.Bundle;
+
+/**
+ * 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.
+ * <p>
+ * Logger names should be in the form of a fully qualified Java class names with
+ * segments separated by full stop ({@code '.'} \u002E). For example:
+ *
+ * <pre>
+ * com.foo.Bar
+ * </pre>
+ *
+ * Logger names exist in a hierarchy. A logger name is said to be an ancestor of
+ * another logger name if the logger name followed by a full stop ({@code '.'}
+ * \u002E) is a prefix of the descendant logger name. The
+ * {@link Logger#ROOT_LOGGER_NAME root logger name} is the top ancestor of the
+ * logger name hierarchy. For example:
+ *
+ * <pre>
+ * com.foo.Bar
+ * com.foo
+ * com
+ * ROOT
+ * </pre>
+ *
+ * @ThreadSafe
+ * @since 1.4
+ * @author $Id$
+ */
+@ProviderType
+public interface LoggerFactory {
+
+ /**
+ * Return the {@link Logger} named with the specified name.
+ *
+ * @param name The name to use for the logger name.
+ * @return The {@link Logger} named with the specified name. If the name
+ * parameter is equal to {@link Logger#ROOT_LOGGER_NAME}, then the
+ * root logger is returned.
+ */
+ Logger getLogger(String name);
+
+ /**
+ * Return the {@link Logger} named with the specified class.
+ *
+ * @param clazz The class to use for the logger name.
+ * @return The {@link Logger} named with the name of the specified class.
+ */
+ Logger getLogger(Class< ? > clazz);
+
+ /**
+ * Return the {@link Logger} of the specified type named with the specified
+ * name.
+ *
+ * @param <L> The 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 The {@link Logger} or {@link FormatterLogger} named with the
+ * specified name. If the name parameter is equal to
+ * {@link Logger#ROOT_LOGGER_NAME}, then the root logger is
+ * returned.
+ * @throws IllegalArgumentException If the specified type is not a supported
+ * Logger type.
+ */
+ <L extends Logger> L getLogger(String name, Class<L> loggerType);
+
+ /**
+ * Return the {@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 The {@link Logger} or {@link FormatterLogger} named with the name
+ * of 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);
+
+ /**
+ * Return the {@link Logger} of the specified type named with the specified
+ * name for the specified bundle.
+ * <p>
+ * This method is not normally used. The other {@code getLogger} methods
+ * return a {@link Logger} associated with the bundle used to obtain this
+ * Logger Factory service. This method is used to obtain a {@link Logger}
+ * for the specified bundle which may be useful to code which is logging on
+ * behalf of another bundle.
+ *
+ * @param <L> The Logger type.
+ * @param bundle The bundle associated with the Logger.
+ * @param name The name to use for the logger name.
+ * @param loggerType The type of Logger. Can be {@link Logger} or
+ * {@link FormatterLogger}.
+ * @return The {@link Logger} or {@link FormatterLogger} named with the
+ * specified name for the specified bundle. If the name parameter is
+ * equal to {@link Logger#ROOT_LOGGER_NAME}, then the root logger is
+ * returned.
+ * @throws IllegalArgumentException If the specified type is not a supported
+ * Logger type or the specified Bundle is not a resolved bundle.
+ */
+ <L extends Logger> L getLogger(Bundle bundle, String name,
+ Class<L> loggerType);
+}
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/package-info.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/package-info.java
index 9280990..81c287a 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/package-info.java
+++ b/bundles/org.eclipse.osgi.services/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.services/src/org/osgi/service/log/packageinfo b/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/packageinfo
deleted file mode 100644
index 0117a56..0000000
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/log/packageinfo
+++ /dev/null
@@ -1 +0,0 @@
-version 1.3
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/Constants.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/Constants.java
index 0b74bf5..2747cd8 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/Constants.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/framework/Constants.java
@@ -814,7 +814,6 @@
*
* @see #FRAGMENT_HOST
* @see #EXTENSION_FRAMEWORK
- * @see #EXTENSION_BOOTCLASSPATH
* @since 1.3
*/
String EXTENSION_DIRECTIVE = "extension";
@@ -840,7 +839,6 @@
* Manifest header directive value identifying the type of extension
* fragment. An extension fragment type of bootclasspath indicates that the
* extension fragment is to be loaded by the boot class loader.
- *
* <p>
* The directive value is encoded in the Fragment-Host manifest header like:
*
@@ -850,6 +848,7 @@
*
* @see #EXTENSION_DIRECTIVE
* @since 1.3
+ * @deprecated As of 1.9.
*/
String EXTENSION_BOOTCLASSPATH = "bootclasspath";
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
index be65488..5fe2297 100644
--- 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
@@ -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.
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 5416267..a9cc36a 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
@@ -23,13 +23,13 @@
* format strings.
* <p>
* Messages can be formatted by the Logger once the Logger determines the log
- * level is enabled. Use a left curly bracket (<code>'{' \u007B</code>) followed
- * by a right curly bracket (<code>'}' \u007D</code>) as a place holder for an
- * argument: <code>"{}"</code>. If you need to use the literal <code>"{}"</code>
- * in the formatted message, precede the place holder with a reverse solidus
- * ({@code '\' \u005C}): <code>"\\{}"</code>. If you need to place a backslash
- * before the place holder, precede the reverse solidus with a reverse solidus:
- * <code>"\\\\{}"</code>.
+ * level is enabled. Use a left curly bracket (<code>'{'</code> \u007B)
+ * followed by a right curly bracket (<code>'}'</code> \u007D) as a place
+ * holder for an argument: <code>"{}"</code>. If you need to use the literal
+ * <code>"{}"</code> in the formatted message, precede the place holder with a
+ * reverse solidus ({@code '\'} \u005C): <code>"\{}"</code>. If you need to
+ * place a backslash before the place holder, precede the reverse solidus with a
+ * reverse solidus: <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
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 a5124e0..b8add76 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
@@ -43,9 +43,10 @@
* <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>
+ * Logger Context's name with {@code org.osgi.service.log.admin} followed by
+ * vertical line ({@code '|'} \u007c). 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";
diff --git a/bundles/org.eclipse.osgi/osgi/src/org/osgi/util/tracker/ServiceTracker.java b/bundles/org.eclipse.osgi/osgi/src/org/osgi/util/tracker/ServiceTracker.java
index 7687fb8..3c9016c 100644
--- a/bundles/org.eclipse.osgi/osgi/src/org/osgi/util/tracker/ServiceTracker.java
+++ b/bundles/org.eclipse.osgi/osgi/src/org/osgi/util/tracker/ServiceTracker.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2000, 2016). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 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.
@@ -394,9 +394,9 @@
* This method is only called when this {@code ServiceTracker} has been
* constructed with a {@code null ServiceTrackerCustomizer} argument.
* <p>
- * This implementation returns the result of calling {@code getService} on
+ * This implementation returns the result of calling {@code getService}, on
* the {@code BundleContext} with which this {@code ServiceTracker} was
- * created passing the specified {@code ServiceReference}.
+ * created, passing the specified {@code ServiceReference}.
* <p>
* This method can be overridden in a subclass to customize the service
* object to be tracked for the service being added. In that case, take care
