Author: oglueck Date: Mon Apr 4 01:35:59 2005 New Revision: 160004 URL: http://svn.apache.org/viewcvs?view=rev&rev=160004 Log: enhanced guide added java.util.logging section
reviewed by: Oleg Kalnichevski Modified: jakarta/commons/proper/httpclient/trunk/xdocs/logging.xml Modified: jakarta/commons/proper/httpclient/trunk/xdocs/logging.xml URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/httpclient/trunk/xdocs/logging.xml?view=diff&r1=160003&r2=160004 ============================================================================== --- jakarta/commons/proper/httpclient/trunk/xdocs/logging.xml (original) +++ jakarta/commons/proper/httpclient/trunk/xdocs/logging.xml Mon Apr 4 01:35:59 2005 @@ -11,14 +11,30 @@ <body> <section name="Logging Practices"> <p> - <em>HttpClient</em> utilizes the logging interface provided by the + Being a library HttpClient is not to dictate which logging framework + the user has to use. Therefore <em>HttpClient</em> utilizes the logging + interface provided by the <a href="http://jakarta.apache.org/commons/logging/"> Jakarta Commons Logging</a> package. <em>Commons Logging</em> provides a simple and generalized <a href="http://jakarta.apache.org/commons/logging/api/index.html"> - log interface</a> to various logging packages. By using + log interface</a> to various logging packages. By using <em>Commons Logging</em>, <em>HttpClient</em> can be configured - for a variety of different logging behaviours. + for a variety of different logging behaviours. That means the user will have + to make a choice which logging framework to use. By default <em>Commons Logging</em> + supports the following logging frameworks: + <ul> + <li><a href="http://logging.apache.org/log4j/docs/index.html">Log4J</a></li> + <li><a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html"> + java.util.logging</a></li> + <li><a href="http://jakarta.apache.org/commons/logging/api/org/apache/commons/logging/impl/SimpleLog.html"> + SimpleLog</a> (internal to <em>Commons Logging</em>)</li> + </ul> + By implementing some simple interfaces <em>Commons Logging</em> can be extended to support + basically any other custom logging framework. + <em>Commons Logging</em> tries to automatically discover the logging framework to use. If it + fails to select the expected one, you must configure <em>Commons Logging</em> by hand. Please + refer to the <em>Commons Logging</em> documentation for more information. </p><p> <em>HttpClient</em> performs two different kinds of logging: the standard context logging used within each class, and wire logging. @@ -52,8 +68,8 @@ <section name="Configuration Examples"> <p> <em>Commons Logging</em> can delegate to a variety of loggers for processing - the actual output. Below are configuration examples for <em>Commons Logging</em> - and <em>Log4j</em>. + the actual output. Below are configuration examples for <em>Commons Logging</em>, + <em>Log4j</em> and <em>java.util.logging</em>. </p> <subsection name="Commons Logging Examples"> <p> @@ -91,7 +107,7 @@ System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br /> System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient", "debug");<br /> </blockquote> - </p> + </p> </subsection> <subsection name="Log4j Examples"> <p> @@ -107,39 +123,57 @@ <p> <u>Enable header wire + context logging</u> - <b>Best for Debugging</b><br /> <blockquote> -log4j.rootLogger=INFO, stdout<br /> -<br /> -log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br /> -log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br /> -log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br /> -<br /> -log4j.logger.httpclient.wire.header=DEBUG<br /> -log4j.logger.org.apache.commons.httpclient=DEBUG<br /> + log4j.rootLogger=INFO, stdout<br /> + <br /> + log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br /> + log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br /> + log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br /> + <br /> + log4j.logger.httpclient.wire.header=DEBUG<br /> + log4j.logger.org.apache.commons.httpclient=DEBUG<br /> </blockquote> </p> <p> <u>Enable full wire(header and content) + context logging</u><br /> <blockquote> -log4j.rootLogger=INFO, stdout<br /> -<br /> -log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br /> -log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br /> -log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br /> -<br /> -log4j.logger.httpclient.wire=DEBUG<br /> -log4j.logger.org.apache.commons.httpclient=DEBUG<br /> + log4j.rootLogger=INFO, stdout<br /> + <br /> + log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br /> + log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br /> + log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br /> + <br /> + log4j.logger.httpclient.wire=DEBUG<br /> + log4j.logger.org.apache.commons.httpclient=DEBUG<br /> + </blockquote> + </p> + <p> + <u>Log wire to file + context logging</u><br /> + <blockquote> + log4j.rootLogger=INFO<br /> + <br /> + log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br /> + log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br /> + log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br /> + <br /> + log4j.appender.F=org.apache.log4j.FileAppender<br /> + log4j.appender.F.File=wire.log<br /> + log4j.appender.F.layout=org.apache.log4j.PatternLayout<br /> + log4j.appender.F.layout.ConversionPattern =%5p [%c] %m%n<br /> + <br /> + log4j.logger.httpclient.wire=DEBUG, F<br /> + log4j.logger.org.apache.commons.httpclient=DEBUG, stdout<br /> </blockquote> </p> <p> <u>Enable just context logging</u><br /> <blockquote> -log4j.rootLogger=INFO, stdout<br /> -<br /> -log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br /> -log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br /> -log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br /> -<br /> -log4j.logger.org.apache.commons.httpclient=DEBUG<br /> + log4j.rootLogger=INFO, stdout<br /> + <br /> + log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br /> + log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br /> + log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br /> + <br /> + log4j.logger.org.apache.commons.httpclient=DEBUG<br /> </blockquote> </p> <p>Note that the default configuration for Log4J is very @@ -148,6 +182,78 @@ best reference for how to configure Log4J. It is available at <a href="http://logging.apache.org/log4j/docs/manual.html">http://logging.apache.org/log4j/docs/manual.html</a> </p> + </subsection> + <subsection name="java.util.logging Examples"> + <p> + Since JDK 1.4 there has been a package + <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html"> + java.util.logging</a> that provides a + logging framework similar to <em>Log4J</em>. By default it reads a config file from + <code>$JAVA_HOME/jre/lib/logging.properties</code> which looks like this + (comments stripped): + <blockquote> + handlers=java.util.logging.ConsoleHandler<br/> + .level=INFO<br/> + java.util.logging.FileHandler.pattern = %h/java%u.log<br/> + java.util.logging.FileHandler.limit = 50000<br/> + java.util.logging.FileHandler.count = 1<br/> + java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter<br/> + java.util.logging.ConsoleHandler.level = INFO<br/> + java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter<br/> + com.xyz.foo.level = SEVERE<br/> + </blockquote> + To customize logging a custom <code>logging.properties</code> file should be created + in the project directory. The location of this file must be passed to the JVM as a + system property. This can be done on the command line like so: + <blockquote> + $JAVA_HOME/java -Djava.util.logging.config.file=$HOME/myapp/logging.properties + -classpath $HOME/myapp/target/classes com.myapp.Main + </blockquote> + Alternatively + <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/LogManager.html#readConfiguration(java.io.InputStream)"> + LogManager#readConfiguration(InputStream)</a> can be used to pass it the desired + configuration. + </p> + <p> + <u>Enable header wire + context logging</u> - <b>Best for Debugging</b><br /> + <blockquote> + .level=INFO<br/> + <br /> + handlers=java.util.logging.ConsoleHandler<br/> + java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter<br/> + <br /> + httpclient.wire.header.level=FINEST<br /> + org.apache.commons.httpclient.level=FINEST<br /> + </blockquote> + </p> + <p> + <u>Enable full wire(header and content) + context logging</u><br /> + <blockquote> + .level=INFO<br/> + <br /> + handlers=java.util.logging.ConsoleHandler<br/> + java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter<br/> + <br /> + httpclient.wire.level=FINEST<br /> + org.apache.commons.httpclient.level=FINEST<br /> + </blockquote> + </p> + <p> + <u>Enable just context logging</u><br /> + <blockquote> + .level=INFO<br/> + <br /> + handlers=java.util.logging.ConsoleHandler<br/> + java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter<br/> + <br /> + org.apache.commons.httpclient.level=FINEST<br /> + </blockquote> + </p> + <p> + More detailed information is available from the + <a href="http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html"> + Java Logging documentation</a>. + </p> </subsection> </section> </body> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]