[slf4j-dev] svn commit: r987 - slf4j/trunk/slf4j-site/src/site/pages

Thu Feb 21 22:03:55 CET 2008

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

