Bug 260672 Graduating Extended Logging bundle (org.eclipse.equinox.log)

Adding Javadoc

8 files changed, 204 insertions, 11 deletions

diff --git a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogEntry.java b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogEntry.java
index bedd08e08..3bc81c5df 100644
--- a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogEntry.java
+++ b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogEntry.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2008 Cognos Incorporated, IBM Corporation and others
+ * Copyright (c) 2006-2009 IBM Corporation and others
  * All rights reserved. This program and the accompanying materials are made
  * available under the terms of the Eclipse Public License v1.0 which
  * accompanies this distribution, and is available at
@@ -8,15 +8,61 @@
 package org.eclipse.equinox.log;
 
 import org.osgi.service.log.LogEntry;
+import org.osgi.service.log.LogListener;
 
+/**
+ * Extends the OSGi Log Services <code>LogEntry</code> object to provide additional context information.
+ * Otherwise similarly accessible by registering a <code>LogListener</code> object.
+ * 
+ * @ThreadSafe
+ * @see LogListener
+ */
 public interface ExtendedLogEntry extends LogEntry {
+
+	/**
+	 * Returns the logger name associated with this <code>LogEntry</code>
+	 * object.
+	 * 
+	 * @return <code>String</code> containing the logger name associated with this
+	 *         <code>LogEntry</code> object;<code>null</code> if no logger name is
+	 *         associated with this <code>LogEntry</code> object.
+	 */
 	String getLoggerName();
 
+	/**
+	 * Returns the context associated with this <code>LogEntry</code>
+	 * object.
+	 * 
+	 * @return <code>Object</code> containing the context associated with this
+	 *         <code>LogEntry</code> object;<code>null</code> if no context is
+	 *         associated with this <code>LogEntry</code> object.
+	 */
 	Object getContext();
 
+	/**
+	 * Returns the thread id of the logging thread associated with this <code>LogEntry</code>
+	 * object.
+	 * 
+	 * @return <code>long</code> containing the thread id associated with this
+	 *         <code>LogEntry</code> object.
+	 */
 	long getThreadId();
 
+	/**
+	 * Returns the thread name of the logging thread associated with this <code>LogEntry</code>
+	 * object.
+	 * 
+	 * @return <code>String</code> containing the message associated with this
+	 *         <code>LogEntry</code> object.
+	 */
 	String getThreadName();
 
+	/**
+	 * Returns the log sequence number associated with this <code>LogEntry</code>
+	 * object. 
+	 * 
+	 * @return <code>long</code> containing the sequence number associated with this
+	 *         <code>LogEntry</code> object.
+	 */
 	long getSequenceNumber();
 }
diff --git a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogReaderService.java b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogReaderService.java
index 7b81d958e..dce75997d 100644
--- a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogReaderService.java
+++ b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogReaderService.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2008 Cognos Incorporated, IBM Corporation and others
+ * Copyright (c) 2006-2009 IBM Corporation and others
  * All rights reserved. This program and the accompanying materials are made
  * available under the terms of the Eclipse Public License v1.0 which
  * accompanies this distribution, and is available at
@@ -7,10 +7,33 @@
  ******************************************************************************/
 package org.eclipse.equinox.log;
 
-import org.osgi.service.log.LogListener;
-import org.osgi.service.log.LogReaderService;
+import org.osgi.service.log.*;
 
+/**
+ * Extends the OSGi Log Service's LogReaderService to allow better control of log listeners.
+ * @ThreadSafe
+ * @see LogListener
+ */
 public interface ExtendedLogReaderService extends LogReaderService {
-
+	/**
+	 * Subscribes to <code>LogEntry</code> objects.
+	 * 
+	 * <p>
+	 * This method registers a <code>LogListener</code> object with the Log Reader
+	 * Service with a <code>LogFilter</code> to allow pre-filtering of interesting log entries.
+	 * The <code>LogListener.logged(LogEntry)</code> method will be
+	 * called for each <code>LogEntry</code> object placed into the log that matches the filter.
+	 * 
+	 * @param listener A <code>LogListener</code> object to register; the
+	 *        <code>LogListener</code> object is used to receive <code>LogEntry</code>
+	 *        objects.
+	 * @param filter A <code>LogFilter</code> object to register; the
+	 *        <code>LogFilter</code> object is used to filter <code>LogEntry</code>
+	 *        objects before sending them to the associated <code>LogListener</code>.
+	 * @see LogListener
+	 * @see LogFilter
+	 * @see LogEntry
+	 * @see LogReaderService#addLogListener(LogListener)
+	 */
 	public void addLogListener(LogListener listener, LogFilter filter);
 }
diff --git a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogService.java b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogService.java
index 284e5e93c..18383c28c 100644
--- a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogService.java
+++ b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/ExtendedLogService.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2008 Cognos Incorporated, IBM Corporation and others
+ * Copyright (c) 2006-2009 IBM Corporation and others
  * All rights reserved. This program and the accompanying materials are made
  * available under the terms of the Eclipse Public License v1.0 which
  * accompanies this distribution, and is available at
@@ -10,11 +10,29 @@ package org.eclipse.equinox.log;
 import org.osgi.framework.Bundle;
 import org.osgi.service.log.LogService;
 
+/**
+ * Extends the OSGi <code>Log Service</code> to support the use of named loggers that provide
+ * some additional context when logging.
+ * @ThreadSafe
+ * @see Logger
+ */
 public interface ExtendedLogService extends LogService, Logger {
 
+	/**
+	 * Returns the <code>Logger<code> object associated with this logger name for the bundle that retrieved this log service.
+	 * If loggerName is null the default <code>Logger</code> for this bundle is returned. 
+	 * 
+	 * @param loggerName The logger name. 
+	 * @return <code>Logger</code> associated with the logger name.
+	 */
 	public Logger getLogger(String loggerName);
 
 	/**
+	 * Returns the logger associated with this logger name and bundle.
+	 * 
+	 * @param loggerName The logger name. 
+	 * @param bundle The bundles associated with this logger. If null the bundle that retrieved this log service is used.
+	 * @return <code>Logger</code> associated with the logger name.
 	* @throws SecurityException if the caller does not have <code>LogPermission[*,LOG]</code>.
 	*/
 	public Logger getLogger(Bundle bundle, String loggerName);
diff --git a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogFilter.java b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogFilter.java
index 977f2f685..6dcb6b298 100644
--- a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogFilter.java
+++ b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogFilter.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2008 Cognos Incorporated, IBM Corporation and others
+ * Copyright (c) 2006-2009 IBM Corporation and others
  * All rights reserved. This program and the accompanying materials are made
  * available under the terms of the Eclipse Public License v1.0 which
  * accompanies this distribution, and is available at
@@ -8,7 +8,22 @@
 package org.eclipse.equinox.log;
 
 import org.osgi.framework.Bundle;
+import org.osgi.service.log.LogEntry;
 
+/**
+ * A <code>LogFilter</code> is used to pre-filter log requests before sending events to a <code>LogListener</code>.
+ * @ThreadSafe
+ * @see ExtendedLogReaderService#addLogListener(org.osgi.service.log.LogListener, LogFilter)
+ */
 public interface LogFilter {
-	boolean isLoggable(Bundle b, String loggerName, int logLevel);
+
+	/**
+	 * @param bundle The logging bundle
+	 * @param loggerName The name of the <code>Logger<code>
+	 * @param logLevel The log level or severity
+	 * @see LogEntry
+	 * @see Logger
+	 * @see ExtendedLogReaderService#addLogListener(org.osgi.service.log.LogListener, LogFilter)
+	 */
+	boolean isLoggable(Bundle bundle, String loggerName, int logLevel);
 }
diff --git a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogPermission.java b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogPermission.java
index 647670a99..3fff36d68 100644
--- a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogPermission.java
+++ b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogPermission.java
@@ -1,13 +1,38 @@
+/*******************************************************************************
+ * Copyright (c) 2009 IBM Corporation and others
+ * All rights reserved. This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ ******************************************************************************/
 package org.eclipse.equinox.log;
 
 import java.security.Permission;
 import java.security.PermissionCollection;
 
+/**
+ * Indicates a bundle's authority to log on behalf of other bundles.
+ * 
+ * This permission has only a single action: LOG.
+ * 
+ * @ThreadSafe
+ * @since 1.1
+ */
 public class LogPermission extends Permission {
 	private static final long serialVersionUID = -441193976837153362L;
 	private static final String ALL = "*"; //$NON-NLS-1$
+
+	/**
+	 * The action string <code>log</code>.
+	 */
 	public static final String LOG = "log"; //$NON-NLS-1$
 
+	/**
+	 * Create a new LogPermission.
+	 * 
+	 * @param name Name must be &quot;*&quot;.
+	 * @param actions <code>log</code> or &quot;*&quot;.
+	 */
 	public LogPermission(String name, String actions) {
 		super(name);
 		if (!name.equals(ALL))
diff --git a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogPermissionCollection.java b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogPermissionCollection.java
index 914147574..ea5a7a34e 100644
--- a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogPermissionCollection.java
+++ b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/LogPermissionCollection.java
@@ -1,3 +1,10 @@
+/*******************************************************************************
+ * Copyright (c) 2009 IBM Corporation and others
+ * All rights reserved. This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License v1.0 which
+ * accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ ******************************************************************************/
 package org.eclipse.equinox.log;
 
 import java.security.Permission;
@@ -5,6 +12,13 @@ import java.security.PermissionCollection;
 import java.util.Enumeration;
 import java.util.NoSuchElementException;
 
+/**
+ * Stores a set of <code>LogPermission</code> permissions.
+ * 
+ * @see java.security.Permission
+ * @see java.security.Permissions
+ * @see java.security.PermissionCollection
+ */
 public final class LogPermissionCollection extends PermissionCollection {
 	private static final long serialVersionUID = -1955409691185916778L;
 	LogPermission logPermission;
diff --git a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/Logger.java b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/Logger.java
index a9b74d125..a40099761 100644
--- a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/Logger.java
+++ b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/Logger.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2008 Cognos Incorporated, IBM Corporation and others
+ * Copyright (c) 2006-2009 IBM Corporation and others
  * All rights reserved. This program and the accompanying materials are made
  * available under the terms of the Eclipse Public License v1.0 which
  * accompanies this distribution, and is available at
@@ -8,22 +8,70 @@
 package org.eclipse.equinox.log;
 
 import org.osgi.framework.ServiceReference;
+import org.osgi.service.log.LogService;
 
 public interface Logger {
+	/**
+	 * @see LogService#log(int, String)
+	 */
 	public void log(int level, String message);
 
+	/**
+	 * @see LogService#log(int, String, Throwable)
+	 */
 	public void log(int level, String message, Throwable exception);
 
+	/**
+	 * @see LogService#log(ServiceReference, int, String)
+	 */
 	public void log(ServiceReference sr, int level, String message);
 
+	/**
+	 * @see LogService#log(ServiceReference, int, String, Throwable)
+	 */
 	public void log(ServiceReference sr, int level, String message, Throwable exception);
 
-	// new methods
+	/**
+	 * Extends the <code>LogService</code>
+	 * Logs a message with a context object
+	 * 
+	 * @param context The context object this message is associated with.
+	 * @param level The log level or severity of the message.
+	 * @param message A human readable string to associate with log entry.
+	 * @see LogService#log(int, String)
+	 */
 	public void log(Object context, int level, String message);
 
+	/**
+	 * Logs a message with an exception associated and a
+	 * context object.
+	 * 
+	 * 
+	 * @param context The context object this message is associated with.
+	 * @param level The log level or severity of the message.
+	 * @param message A human readable string to associate with log entry.
+	 * @param exception The exception associated with this entry
+	 * @see LogService#log(int, String, Throwable)
+	 */
 	public void log(Object context, int level, String message, Throwable exception);
 
+	/**
+	 * Pre-checks if there are LogListeners who are listening for a matching log entry from this <code>Logger</code>. 
+	 * 
+	 * @param level The log level or severity of the message.
+	 * @return <code>boolean</code> True if there a LogListener listening that can handle a log entry for this log level; false otherwise. 
+	 * @see ExtendedLogReaderService#addLogListener(org.osgi.service.log.LogListener, LogFilter)
+	 * @see LogFilter
+	 */
 	public boolean isLoggable(int level);
 
+	/**
+	 * Returns the name associated with this <code>Logger</code>
+	 * object.
+	 * 
+	 * @return <code>String</code> containing the name associated with this
+	 *         <code>Logger</code> object;<code>null</code> if no name is
+	 *         associated.
+	 */
 	public String getName();
 }
diff --git a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/SynchronousLogListener.java b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/SynchronousLogListener.java
index c07b9d5b9..807a1d582 100644
--- a/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/SynchronousLogListener.java
+++ b/bundles/org.eclipse.equinox.log/src/org/eclipse/equinox/log/SynchronousLogListener.java
@@ -9,6 +9,10 @@ package org.eclipse.equinox.log;
 
 import org.osgi.service.log.LogListener;
 
+/**
+ * Marker interface to denotes a log listener that should be called on the logging thread
+ * @see LogListener
+ */
 public interface SynchronousLogListener extends LogListener {
-	// denotes a log listener that should be called on the logging thread
+	//
 }