You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/03/19 19:52:55 UTC
[commons-logging] 02/02: Javadoc: Convert package.html to package-info.java
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-logging.git
commit d376d3128663e53de4af948e161291e7ec0c6ec1
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Mar 19 15:52:49 2023 -0400
Javadoc: Convert package.html to package-info.java
---
.../org/apache/commons/logging/package-info.java | 216 +++++++++++++++++
.../java/org/apache/commons/logging/package.html | 255 ---------------------
2 files changed, 216 insertions(+), 255 deletions(-)
diff --git a/src/main/java/org/apache/commons/logging/package-info.java b/src/main/java/org/apache/commons/logging/package-info.java
new file mode 100644
index 0000000..f6cd5dd
--- /dev/null
+++ b/src/main/java/org/apache/commons/logging/package-info.java
@@ -0,0 +1,216 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+
+/**
+ * Simple wrapper API around multiple logging APIs.
+ *
+ * <h2>Overview</h2>
+ * <p>This package provides an API for logging in server-based applications that
+ * can be used around a variety of different logging implementations, including
+ * prebuilt support for the following:</p>
+ * <ul>
+ * <li><a href="http://logging.apache.org/log4j/">Log4J</a> (version 1.2 or later)
+ * from Apache's Logging project. Each named <a href="Log.html">Log</a>
+ * instance is connected to a corresponding Log4J Logger.</li>
+ * <li><a href="http://java.sun.com/j2se/1.4/docs/guide/util/logging/index.html">
+ * JDK Logging API</a>, included in JDK 1.4 or later systems. Each named
+ * <a href="Log.html">Log</a> instance is connected to a corresponding
+ * <code>java.util.logging.Logger</code> instance.</li>
+ * <li><a href="http://avalon.apache.org/logkit/">LogKit</a> from Apache's
+ * Avalon project. Each named <a href="Log.html">Log</a> instance is
+ * connected to a corresponding LogKit <code>Logger</code>.</li>
+ * <li><a href="impl/NoOpLog.html">NoOpLog</a> implementation that simply swallows
+ * all log output, for all named <a href="Log.html">Log</a> instances.</li>
+ * <li><a href="impl/SimpleLog.html">SimpleLog</a> implementation that writes all
+ * log output, for all named <a href="Log.html">Log</a> instances, to
+ * System.err.</li>
+ * </ul>
+ * <h2>Quick Start Guide</h2>
+ * <p>For those impatient to just get on with it, the following example
+ * illustrates the typical declaration and use of a logger that is named (by
+ * convention) after the calling class:
+ * <pre>
+ * import org.apache.commons.logging.Log;
+ * import org.apache.commons.logging.LogFactory;
+ * public class Foo {
+ * private Log log = LogFactory.getLog(Foo.class);
+ * public void foo() {
+ * ...
+ * try {
+ * if (log.isDebugEnabled()) {
+ * log.debug("About to do something to object " + name);
+ * }
+ * name.bar();
+ * } catch (IllegalStateException e) {
+ * log.error("Something bad happened to " + name, e);
+ * }
+ * ...
+ * }
+ * </pre>
+ * <p>Unless you configure things differently, all log output will be written
+ * to System.err. Therefore, you really will want to review the remainder of
+ * this page in order to understand how to configure logging for your
+ * application.</p>
+ * <h2>Configuring the Commons Logging Package</h2>
+ * <h3>Choosing a <code>LogFactory</code> Implementation</h3>
+ * <p>From an application perspective, the first requirement is to retrieve an
+ * object reference to the <code>LogFactory</code> instance that will be used
+ * to create <code><a href="Log.html">Log</a></code> instances for this
+ * application. This is normally accomplished by calling the static
+ * <code>getFactory()</code> method. This method implements the following
+ * discovery algorithm to select the name of the <code>LogFactory</code>
+ * implementation class this application wants to use:</p>
+ * <ul>
+ * <li>Check for a system property named
+ * <code>org.apache.commons.logging.LogFactory</code>.</li>
+ * <li>Use the JDK 1.3 JAR Services Discovery mechanism (see
+ * <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html">
+ * http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html</a> for
+ * more information) to look for a resource named
+ * <code>META-INF/services/org.apache.commons.logging.LogFactory</code>
+ * whose first line is assumed to contain the desired class name.</li>
+ * <li>Look for a properties file named <code>commons-logging.properties</code>
+ * visible in the application class path, with a property named
+ * <code>org.apache.commons.logging.LogFactory</code> defining the
+ * desired implementation class name.</li>
+ * <li>Fall back to a default implementation, which is described
+ * further below.</li>
+ * </ul>
+ * <p>If a <code>commons-logging.properties</code> file is found, all of the
+ * properties defined there are also used to set configuration attributes on
+ * the instantiated <code>LogFactory</code> instance.</p>
+ * <p>Once an implementation class name is selected, the corresponding class is
+ * loaded from the current Thread context class loader (if there is one), or
+ * from the class loader that loaded the <code>LogFactory</code> class itself
+ * otherwise. This allows a copy of <code>commons-logging.jar</code> to be
+ * shared in a multiple class loader environment (such as a servlet container),
+ * but still allow each web application to provide its own <code>LogFactory</code>
+ * implementation, if it so desires. An instance of this class will then be
+ * created, and cached per class loader.
+ * <h3>The Default <code>LogFactory</code> Implementation</h3>
+ * <p>The Logging Package APIs include a default <code>LogFactory</code>
+ * implementation class (<a href="impl/LogFactoryImpl.html">
+ * org.apache.commons.logging.impl.LogFactoryImpl</a>) that is selected if no
+ * other implementation class name can be discovered. Its primary purpose is
+ * to create (as necessary) and return <a href="Log.html">Log</a> instances
+ * in response to calls to the <code>getInstance()</code> method. The default
+ * implementation uses the following rules:</p>
+ * <ul>
+ * <li>At most one <code>Log</code> instance of the same name will be created.
+ * Subsequent <code>getInstance()</code> calls to the same
+ * <code>LogFactory</code> instance, with the same name or <code>Class</code>
+ * parameter, will return the same <code>Log</code> instance.</li>
+ * <li>When a new <code>Log</code> instance must be created, the default
+ * <code>LogFactory</code> implementation uses the following discovery
+ * process:
+ * <ul>
+ * <li>Look for a configuration attribute of this factory named
+ * <code>org.apache.commons.logging.Log</code> (for backwards
+ * compatibility to pre-1.0 versions of this API, an attribute
+ * <code>org.apache.commons.logging.log</code> is also consulted).</li>
+ * <li>Look for a system property named
+ * <code>org.apache.commons.logging.Log</code> (for backwards
+ * compatibility to pre-1.0 versions of this API, a system property
+ * <code>org.apache.commons.logging.log</code> is also consulted).</li>
+ * <li>If the Log4J logging system is available in the application
+ * class path, use the corresponding wrapper class
+ * (<a href="impl/Log4JLogger.html">Log4JLogger</a>).</li>
+ * <li>If the application is executing on a JDK 1.4 system, use
+ * the corresponding wrapper class
+ * (<a href="impl/Jdk14Logger.html">Jdk14Logger</a>).</li>
+ * <li>Fall back to the default simple logging implementation
+ * (<a href="impl/SimpleLog.html">SimpleLog</a>).</li>
+ * </ul></li>
+ * <li>Load the class of the specified name from the thread context class
+ * loader (if any), or from the class loader that loaded the
+ * <code>LogFactory</code> class otherwise.</li>
+ * <li>Instantiate an instance of the selected <code>Log</code>
+ * implementation class, passing the specified name as the single
+ * argument to its constructor.</li>
+ * </ul>
+ * <p>See the <a href="impl/SimpleLog.html">SimpleLog</a> Javadocs for detailed
+ * configuration information for this default implementation.</p>
+ * <h3>Configuring the Underlying Logging System</h3>
+ * <p>The basic principle is that the user is totally responsible for the
+ * configuration of the underlying logging system.
+ * Commons-logging should not change the existing configuration.</p>
+ * <p>Each individual <a href="Log.html">Log</a> implementation may
+ * support its own configuration properties. These will be documented in the
+ * class descriptions for the corresponding implementation class.</p>
+ * <p>Finally, some <code>Log</code> implementations (such as the one for Log4J)
+ * require an external configuration file for the entire logging environment.
+ * This file should be prepared in a manner that is specific to the actual logging
+ * technology being used.</p>
+ * <h2>Using the Logging Package APIs</h2>
+ * <p>Use of the Logging Package APIs, from the perspective of an application
+ * component, consists of the following steps:</p>
+ * <ol>
+ * <li>Acquire a reference to an instance of
+ * <a href="Log.html">org.apache.commons.logging.Log</a>, by calling the
+ * factory method
+ * <a href="LogFactory.html#getInstance(java.lang.String)">
+ * LogFactory.getInstance(String name)</a>. Your application can contain
+ * references to multiple loggers that are used for different
+ * purposes. A typical scenario for a server application is to have each
+ * major component of the server use its own Log instance.</li>
+ * <li>Cause messages to be logged (if the corresponding detail level is enabled)
+ * by calling appropriate methods (<code>trace()</code>, <code>debug()</code>,
+ * <code>info()</code>, <code>warn()</code>, <code>error</code>, and
+ * <code>fatal()</code>).</li>
+ * </ol>
+ * <p>For convenience, <code>LogFactory</code> also offers a static method
+ * <code>getLog()</code> that combines the typical two-step pattern:</p>
+ * <pre>
+ * Log log = LogFactory.getFactory().getInstance(Foo.class);
+ * </pre>
+ * <p>into a single method call:</p>
+ * <pre>
+ * Log log = LogFactory.getLog(Foo.class);
+ * </pre>
+ * <p>For example, you might use the following technique to initialize and
+ * use a <a href="Log.html">Log</a> instance in an application component:</p>
+ * <pre>
+ * import org.apache.commons.logging.Log;
+ * import org.apache.commons.logging.LogFactory;
+ * public class MyComponent {
+ * protected Log log =
+ * LogFactory.getLog(MyComponent.class);
+ * // Called once at startup time
+ * public void start() {
+ * ...
+ * log.info("MyComponent started");
+ * ...
+ * }
+ * // Called once at shutdown time
+ * public void stop() {
+ * ...
+ * log.info("MyComponent stopped");
+ * ...
+ * }
+ * // Called repeatedly to process a particular argument value
+ * // which you want logged if debugging is enabled
+ * public void process(String value) {
+ * ...
+ * // Do the string concatenation only if logging is enabled
+ * if (log.isDebugEnabled())
+ * log.debug("MyComponent processing " + value);
+ * ...
+ * }
+ * }
+ * </pre>
+ */
+package org.apache.commons.logging;
\ No newline at end of file
diff --git a/src/main/java/org/apache/commons/logging/package.html b/src/main/java/org/apache/commons/logging/package.html
deleted file mode 100644
index cbe8cbe..0000000
--- a/src/main/java/org/apache/commons/logging/package.html
+++ /dev/null
@@ -1,255 +0,0 @@
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You 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.
-
--->
-
-<body>
-<p>Simple wrapper API around multiple logging APIs.</p>
-
-
-<h2>Overview</h2>
-
-<p>This package provides an API for logging in server-based applications that
-can be used around a variety of different logging implementations, including
-prebuilt support for the following:</p>
-<ul>
-<li><a href="http://logging.apache.org/log4j/">Log4J</a> (version 1.2 or later)
- from Apache's Logging project. Each named <a href="Log.html">Log</a>
- instance is connected to a corresponding Log4J Logger.</li>
-<li><a href="http://java.sun.com/j2se/1.4/docs/guide/util/logging/index.html">
- JDK Logging API</a>, included in JDK 1.4 or later systems. Each named
- <a href="Log.html">Log</a> instance is connected to a corresponding
- <code>java.util.logging.Logger</code> instance.</li>
-<li><a href="http://avalon.apache.org/logkit/">LogKit</a> from Apache's
- Avalon project. Each named <a href="Log.html">Log</a> instance is
- connected to a corresponding LogKit <code>Logger</code>.</li>
-<li><a href="impl/NoOpLog.html">NoOpLog</a> implementation that simply swallows
- all log output, for all named <a href="Log.html">Log</a> instances.</li>
-<li><a href="impl/SimpleLog.html">SimpleLog</a> implementation that writes all
- log output, for all named <a href="Log.html">Log</a> instances, to
- System.err.</li>
-</ul>
-
-
-<h2>Quick Start Guide</h2>
-
-<p>For those impatient to just get on with it, the following example
-illustrates the typical declaration and use of a logger that is named (by
-convention) after the calling class:
-
-<pre>
- import org.apache.commons.logging.Log;
- import org.apache.commons.logging.LogFactory;
-
- public class Foo {
-
- private Log log = LogFactory.getLog(Foo.class);
-
- public void foo() {
- ...
- try {
- if (log.isDebugEnabled()) {
- log.debug("About to do something to object " + name);
- }
- name.bar();
- } catch (IllegalStateException e) {
- log.error("Something bad happened to " + name, e);
- }
- ...
- }
-</pre>
-
-<p>Unless you configure things differently, all log output will be written
-to System.err. Therefore, you really will want to review the remainder of
-this page in order to understand how to configure logging for your
-application.</p>
-
-
-<h2>Configuring the Commons Logging Package</h2>
-
-
-<h3>Choosing a <code>LogFactory</code> Implementation</h3>
-
-<p>From an application perspective, the first requirement is to retrieve an
-object reference to the <code>LogFactory</code> instance that will be used
-to create <code><a href="Log.html">Log</a></code> instances for this
-application. This is normally accomplished by calling the static
-<code>getFactory()</code> method. This method implements the following
-discovery algorithm to select the name of the <code>LogFactory</code>
-implementation class this application wants to use:</p>
-<ul>
-<li>Check for a system property named
- <code>org.apache.commons.logging.LogFactory</code>.</li>
-<li>Use the JDK 1.3 JAR Services Discovery mechanism (see
- <a href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html">
- http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html</a> for
- more information) to look for a resource named
- <code>META-INF/services/org.apache.commons.logging.LogFactory</code>
- whose first line is assumed to contain the desired class name.</li>
-<li>Look for a properties file named <code>commons-logging.properties</code>
- visible in the application class path, with a property named
- <code>org.apache.commons.logging.LogFactory</code> defining the
- desired implementation class name.</li>
-<li>Fall back to a default implementation, which is described
- further below.</li>
-</ul>
-
-<p>If a <code>commons-logging.properties</code> file is found, all of the
-properties defined there are also used to set configuration attributes on
-the instantiated <code>LogFactory</code> instance.</p>
-
-<p>Once an implementation class name is selected, the corresponding class is
-loaded from the current Thread context class loader (if there is one), or
-from the class loader that loaded the <code>LogFactory</code> class itself
-otherwise. This allows a copy of <code>commons-logging.jar</code> to be
-shared in a multiple class loader environment (such as a servlet container),
-but still allow each web application to provide its own <code>LogFactory</code>
-implementation, if it so desires. An instance of this class will then be
-created, and cached per class loader.
-
-
-<h3>The Default <code>LogFactory</code> Implementation</h3>
-
-<p>The Logging Package APIs include a default <code>LogFactory</code>
-implementation class (<a href="impl/LogFactoryImpl.html">
-org.apache.commons.logging.impl.LogFactoryImpl</a>) that is selected if no
-other implementation class name can be discovered. Its primary purpose is
-to create (as necessary) and return <a href="Log.html">Log</a> instances
-in response to calls to the <code>getInstance()</code> method. The default
-implementation uses the following rules:</p>
-<ul>
-<li>At most one <code>Log</code> instance of the same name will be created.
- Subsequent <code>getInstance()</code> calls to the same
- <code>LogFactory</code> instance, with the same name or <code>Class</code>
- parameter, will return the same <code>Log</code> instance.</li>
-<li>When a new <code>Log</code> instance must be created, the default
- <code>LogFactory</code> implementation uses the following discovery
- process:
- <ul>
- <li>Look for a configuration attribute of this factory named
- <code>org.apache.commons.logging.Log</code> (for backwards
- compatibility to pre-1.0 versions of this API, an attribute
- <code>org.apache.commons.logging.log</code> is also consulted).</li>
- <li>Look for a system property named
- <code>org.apache.commons.logging.Log</code> (for backwards
- compatibility to pre-1.0 versions of this API, a system property
- <code>org.apache.commons.logging.log</code> is also consulted).</li>
- <li>If the Log4J logging system is available in the application
- class path, use the corresponding wrapper class
- (<a href="impl/Log4JLogger.html">Log4JLogger</a>).</li>
- <li>If the application is executing on a JDK 1.4 system, use
- the corresponding wrapper class
- (<a href="impl/Jdk14Logger.html">Jdk14Logger</a>).</li>
- <li>Fall back to the default simple logging implementation
- (<a href="impl/SimpleLog.html">SimpleLog</a>).</li>
- </ul></li>
-<li>Load the class of the specified name from the thread context class
- loader (if any), or from the class loader that loaded the
- <code>LogFactory</code> class otherwise.</li>
-<li>Instantiate an instance of the selected <code>Log</code>
- implementation class, passing the specified name as the single
- argument to its constructor.</li>
-</ul>
-
-<p>See the <a href="impl/SimpleLog.html">SimpleLog</a> Javadocs for detailed
-configuration information for this default implementation.</p>
-
-
-<h3>Configuring the Underlying Logging System</h3>
-
-<p>The basic principle is that the user is totally responsible for the
-configuration of the underlying logging system.
-Commons-logging should not change the existing configuration.</p>
-
-<p>Each individual <a href="Log.html">Log</a> implementation may
-support its own configuration properties. These will be documented in the
-class descriptions for the corresponding implementation class.</p>
-
-<p>Finally, some <code>Log</code> implementations (such as the one for Log4J)
-require an external configuration file for the entire logging environment.
-This file should be prepared in a manner that is specific to the actual logging
-technology being used.</p>
-
-
-<h2>Using the Logging Package APIs</h2>
-
-<p>Use of the Logging Package APIs, from the perspective of an application
-component, consists of the following steps:</p>
-<ol>
-<li>Acquire a reference to an instance of
- <a href="Log.html">org.apache.commons.logging.Log</a>, by calling the
- factory method
- <a href="LogFactory.html#getInstance(java.lang.String)">
- LogFactory.getInstance(String name)</a>. Your application can contain
- references to multiple loggers that are used for different
- purposes. A typical scenario for a server application is to have each
- major component of the server use its own Log instance.</li>
-<li>Cause messages to be logged (if the corresponding detail level is enabled)
- by calling appropriate methods (<code>trace()</code>, <code>debug()</code>,
- <code>info()</code>, <code>warn()</code>, <code>error</code>, and
- <code>fatal()</code>).</li>
-</ol>
-
-<p>For convenience, <code>LogFactory</code> also offers a static method
-<code>getLog()</code> that combines the typical two-step pattern:</p>
-<pre>
- Log log = LogFactory.getFactory().getInstance(Foo.class);
-</pre>
-<p>into a single method call:</p>
-<pre>
- Log log = LogFactory.getLog(Foo.class);
-</pre>
-
-<p>For example, you might use the following technique to initialize and
-use a <a href="Log.html">Log</a> instance in an application component:</p>
-<pre>
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
-
-public class MyComponent {
-
- protected Log log =
- LogFactory.getLog(MyComponent.class);
-
- // Called once at startup time
- public void start() {
- ...
- log.info("MyComponent started");
- ...
- }
-
- // Called once at shutdown time
- public void stop() {
- ...
- log.info("MyComponent stopped");
- ...
- }
-
- // Called repeatedly to process a particular argument value
- // which you want logged if debugging is enabled
- public void process(String value) {
- ...
- // Do the string concatenation only if logging is enabled
- if (log.isDebugEnabled())
- log.debug("MyComponent processing " + value);
- ...
- }
-
-}
-</pre>
-
-</body>