Author: ceki Date: Thu Feb 21 22:03:54 2008 New Revision: 987 Added: slf4j/trunk/slf4j-site/src/site/pages/migrator.html
Log: - documenting slf4j-migrator tool Added: slf4j/trunk/slf4j-site/src/site/pages/migrator.html ============================================================================== --- (empty file) +++ slf4j/trunk/slf4j-site/src/site/pages/migrator.html Thu Feb 21 22:03:54 2008 @@ -0,0 +1,169 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd";> +<html xmlns="http://www.w3.org/1999/xhtml";> +<head> +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> +<title>SLF4J Migrator</title> +<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" /> +</head> +<body> + <script> +prefix=''; +</script> + +<script src="templates/header.js"></script> +<div id="left"> + <script src="templates/left.js"></script> +</div> +<div id="right"> + <script src="templates/right.js"></script> +</div> +<div id="content"> + + + <h1>SLF4J Migrator</h1> + + <p>The SLF4J migrator is a small Java tool for migrating Java source + files from the Jakarta Commons Logging (JCL) API to SLF4J. It can + also migrate from the log4j API to SLF4J. + </p> + + <p>The SLF4J migrator consists of a single jar file that can be + launched as a stand-alone java application. Here is the command: + </p> + + <p class="source">java -jar slf4j-migrator-${version}.jar </p> + + <br/> + + <p>Once the application is launched, a window similar to the + following should appear. + </p> + + <p><img src="images/slf4j-migrator.gif"/></p> + + <p>Use the application should be self-explanatory. Please note that + this migration tool does in-place replacement of Java files, meaning + that there will be no back-up copies of modified files. <b>It is + your responsibility to backup your files before using SLF4J + migrator.</b> + </p> + + + <h2>Limitations</h2> + + <p>SLF4J migrator is intended as a simple tool to help you to + migrate your project source using JCL or log4j to SLF4J. It can only + perform elementary conversion steps. Essentially it will replace + appropriate import lines and logger declarations. + </p> + + <p>MyClass is a sample class using JCL. Here it is before:</p> + + <p class="source">package some.package; + +<b>import org.apache.commons.logging.Log; +import org.apache.commons.logging.LogFactory;</b> + +public MyClass { + + + <b>Log logger = LogFactory.getLog(MyClass.class);</b> + + public void someMethod() { + logger.info("Hello world"); + } +}</p> + + and after migration:</p> + + <p class="source">package some.package; + +<b>import org.slf4j.Logger; +import org.slf4j.LoggerFactory;</b> + +public MyClass { + + <b>Logger logger = LoggerFactory.getLogger(MyClass.class);</b> + + public void someMethod() { + logger.info("Hello world"); + } +}</p> + + <br/> + + <p>Altough its conversion rules are elementary, the SLF4J migrator + can still alleviate much of the grunt-work involved in migrating a + Java project from JCL to SLF4J. + </p> + + <p>Migration rules for log4j to SLF4J are similar.</p> + + <h3>General limitations</h3> + + <ul> + + <li>Build scipts are not modified + + <p>Your Ant/Maven/Ivy build scripts need to be modified manualy to + use SLF4J instead of JCL or log4j.</p> + + <p></p> + </li> + + <li>the FATAL level is not supported. + + <p>You have to convert them manually. This is limitation is not + deemed very serious because there are usually very few log + statements bearing the FATAL level. + </p> + + <p> + </p> + </li> + + <li>if a method declares multipe loggers on the same line, the + conversion will not be complete. Example: + + <p class="source"> + public void someMethod(Log l1, Log l2) { + ... + } + + will be converted as + + public void someMethod(Log l1, Logger l2) { + ... + } + </p> + </li> + </ul> + + <h3>Limitations when migrating from log4j</h3> + + <ul> + <li>NDC statements are left as-is + + <p>Since NDC is not supported by SLF4J, the migrator cannot + properly handle NDC statements. You have to migrate them to MDC + manually. Again, this limitation is not deemed serious bebause + there are usually very few NDC statements even in large projects. + </p> + + <p></p> + </li> + + <li>Calls to <code>PropertyConfigurator</code> or + <code>DomConfigurator</code> cannot be migrated since they have no + SLF4J equivalents. + + <p> + </p> + + </li> + </ul> + + + </div> +</body> + </html> \ No newline at end of file _______________________________________________ dev mailing list [email protected] http://www.slf4j.org/mailman/listinfo/dev
