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. + * + *

Overview

+ *

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:

+ * + *

Quick Start Guide

+ *

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: + * 

+ * 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);
+ * }
+ * ...
+ * }
+ *
+ *

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.

+ *

Configuring the Commons Logging Package

+ *

Choosing a LogFactory Implementation

+ *

From an application perspective, the first requirement is to retrieve an + * object reference to the LogFactory instance that will be used + * to create Log instances for this + * application. This is normally accomplished by calling the static + * getFactory() method. This method implements the following + * discovery algorithm to select the name of the LogFactory + * implementation class this application wants to use:

+ * + *

If a commons-logging.properties file is found, all of the + * properties defined there are also used to set configuration attributes on + * the instantiated LogFactory instance.

+ *

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 LogFactory class itself + * otherwise. This allows a copy of commons-logging.jar to be + * shared in a multiple class loader environment (such as a servlet container), + * but still allow each web application to provide its own LogFactory + * implementation, if it so desires. An instance of this class will then be + * created, and cached per class loader. + *

The Default LogFactory Implementation

+ *

The Logging Package APIs include a default LogFactory + * implementation class ( + * org.apache.commons.logging.impl.LogFactoryImpl) that is selected if no + * other implementation class name can be discovered. Its primary purpose is + * to create (as necessary) and return Log instances + * in response to calls to the getInstance() method. The default + * implementation uses the following rules:

+ * + *

See the SimpleLog Javadocs for detailed + * configuration information for this default implementation.

+ *

Configuring the Underlying Logging System

+ *

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.

+ *

Each individual Log implementation may + * support its own configuration properties. These will be documented in the + * class descriptions for the corresponding implementation class.

+ *

Finally, some Log 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.

+ *

Using the Logging Package APIs

+ *

Use of the Logging Package APIs, from the perspective of an application + * component, consists of the following steps:

+ *
    + *
  1. Acquire a reference to an instance of + * org.apache.commons.logging.Log, by calling the + * factory method + * + * LogFactory.getInstance(String name). 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.
    2. + *
  2. Cause messages to be logged (if the corresponding detail level is enabled) + * by calling appropriate methods (trace(), debug(), + * info(), warn(), error, and + * fatal()).
    3. + *
+ *

For convenience, LogFactory also offers a static method + * getLog() that combines the typical two-step pattern:

+ * 
+ * Log log = LogFactory.getFactory().getInstance(Foo.class);
+ *
+ *

into a single method call:

+ * 
+ * Log log = LogFactory.getLog(Foo.class);
+ *
+ *

For example, you might use the following technique to initialize and + * use a Log instance in an application component:

+ * 
+ * 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);
+ * ...
+ * }
+ * }
+ *
+ */ +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 @@ - - - -

Simple wrapper API around multiple logging APIs.

- - -

Overview

- -

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:

- - - -

Quick Start Guide

- -

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: - -

-    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);
-            }
-            ...
-        }
-
- -

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.

- - -

Configuring the Commons Logging Package

- - -

Choosing a LogFactory Implementation

- -

From an application perspective, the first requirement is to retrieve an -object reference to the LogFactory instance that will be used -to create Log instances for this -application. This is normally accomplished by calling the static -getFactory() method. This method implements the following -discovery algorithm to select the name of the LogFactory -implementation class this application wants to use:

- - -

If a commons-logging.properties file is found, all of the -properties defined there are also used to set configuration attributes on -the instantiated LogFactory instance.

- -

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 LogFactory class itself -otherwise. This allows a copy of commons-logging.jar to be -shared in a multiple class loader environment (such as a servlet container), -but still allow each web application to provide its own LogFactory -implementation, if it so desires. An instance of this class will then be -created, and cached per class loader. - - -

The Default LogFactory Implementation

- -

The Logging Package APIs include a default LogFactory -implementation class ( -org.apache.commons.logging.impl.LogFactoryImpl) that is selected if no -other implementation class name can be discovered. Its primary purpose is -to create (as necessary) and return Log instances -in response to calls to the getInstance() method. The default -implementation uses the following rules:

- - -

See the SimpleLog Javadocs for detailed -configuration information for this default implementation.

- - -

Configuring the Underlying Logging System

- -

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.

- -

Each individual Log implementation may -support its own configuration properties. These will be documented in the -class descriptions for the corresponding implementation class.

- -

Finally, some Log 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.

- - -

Using the Logging Package APIs

- -

Use of the Logging Package APIs, from the perspective of an application -component, consists of the following steps:

-
    -
  1. Acquire a reference to an instance of - org.apache.commons.logging.Log, by calling the - factory method - - LogFactory.getInstance(String name). 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.
    2. -
  2. Cause messages to be logged (if the corresponding detail level is enabled) - by calling appropriate methods (trace(), debug(), - info(), warn(), error, and - fatal()).
    3. -
- -

For convenience, LogFactory also offers a static method -getLog() that combines the typical two-step pattern:

-
-  Log log = LogFactory.getFactory().getInstance(Foo.class);
-
-

into a single method call:

-
-  Log log = LogFactory.getLog(Foo.class);
-
- -

For example, you might use the following technique to initialize and -use a Log instance in an application component:

-
-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);
-    ...
-  }
-
-}
-
- -