diff options
author | Simon Kaegi | 2009-03-23 19:15:29 +0000 |
---|---|---|
committer | Simon Kaegi | 2009-03-23 19:15:29 +0000 |
commit | 660ebfc412c97b7ddd6f0ca08342f163b833f2b7 (patch) | |
tree | 912740343c3f16b79f6c084017ea9425cddee14a /bundles/org.eclipse.equinox.log | |
parent | e0dedc4da49e416ec849217854fd282b1d6dfa3d (diff) | |
download | rt.equinox.bundles-660ebfc412c97b7ddd6f0ca08342f163b833f2b7.tar.gz rt.equinox.bundles-660ebfc412c97b7ddd6f0ca08342f163b833f2b7.tar.xz rt.equinox.bundles-660ebfc412c97b7ddd6f0ca08342f163b833f2b7.zip |
Bug 260672 Graduating Extended Logging bundle (org.eclipse.equinox.log)
Adding Javadoc
Diffstat (limited to 'bundles/org.eclipse.equinox.log')
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 "*". + * @param actions <code>log</code> or "*". + */ 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 + // } |