site/pages/compatibility.html

<!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>Compatibility report</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>Compatibility report</h1>

  <p>Given the very large user base of SLF4J, we take backward
  compatibility very seriously. As such, changes that may cause
  incompatibility problems are listed in this page. Moreover, since
  slf4j-api.jar is the main entry point into SLF4J, that is the module
  that will be covered in most detail.
  </p>

  <p>Please note that in many cases incompatibility problems are
  caused by mixing different versions of slf4j artifacts. For example,
  if you are using slf4j-api-1.5.4.jar you should also use
  slf4j-simple-1.5.4.jar, using slf4j-simple-1.4.2.jar will not
  work. The same goes for all other SLF4J artifacts.
  </p>

  <p>The list is computed using <a
  href="http://clirr.sourceforge.net/">clirr</a>. If you have reasons
  to suspect incompatible changes not mentioned here, please kindly
  contact the slf4j developers list.</p>

  <h2><a href="#1_5_7" name="1_5_6">Version 1.5.7 compared to 1.5.6</a></h2>

  <p>No breaking changes to report.</p>

  <h2><a href="#1_5_6" name="1_5_5">Version 1.5.6 compared to 1.5.5</a></h2>


  <table class="bodyTable">
    <tr>
      <th>Severity</th>
      <th>Description</th>
      <th>Class</th>
      <th>Method / Field</th>
    </tr>
    <tr>
      <td>Error</td>
      <td>The&nbsp;number&nbsp;of&nbsp;parameters&nbsp;of SubstituteLoggerFactory
      constructor has changed</td>
      <td>org.slf4j.helpers.SubstituteLoggerFactory</td>
      <td>public SubstituteLoggerFactory(java.util.List)</td>
    </tr>
  </table>

  <p>&nbsp;</p>

  <p>The <code>SubstituteLoggerFactory</code> class is used internally
  by the LoggerFactory class. Changes to the constructor of
  SubstituteLoggerFactory should have strictly no effect on users.
  </p>

  <h2><a href="#1_5_5" name="1_5_4">Version 1.5.5 compared to 1.5.4</a></h2>

  <p>No breaking changes to report.</p>

  <h2><a href="#1_5_4" name="1_5_4">Version 1.5.4 compared to 1.5.3</a></h2>

  <h3>slf4j-api module, list of breaking changes:</h3>


  <table class="bodyTable">
    <tr>
      <th>Severity</th>
      <th>Description</th>
      <th>Class</th>
      <th>Method / Field</th>
    </tr>
    <tr>
      <td>Error</td>
      <td>Method 'hasReferences()' has been added to an interface</td>
      <td>org.slf4j.Marker</td>
      <td>public boolean hasReferences()</td>
    </tr>
    <tr class="alt">
      <td>Info</td>
      <td>Method 'hasChildren()' was deprecated</td>
      <td>org.slf4j.Marker</td>
      <td>public boolean hasChildren()</td>
    </tr>

  </table>

  <p>&nbsp;</p>

  <p>The <code>hasChildren()</code> and other documentation in the
  Marker interface was misleading users to think in terms of parent
  child relationship for markers. However, as <a
  href="http://bugzilla.slf4j.org/show_bug.cgi?id=100">bug 100</a>
  illustrates, associating markers as parents and children is not very
  helpful. It is much better to think of markers in terms of abstract
  graphs. As such, we now say that a marker contains (zero or more)
  <code>references</code> to other markers.
  </p>

  <p>This breaking change is justified because it corrects a
  conceptual error in the design. Previously, it was all too easy for
  developers to get confused and incorrectly link markers
  together.</p>

  <h2><a href="#1_5_3" name="1_5_3">Version 1.5.3 compared to 1.5.2</a></h2>

  <h3>slf4j-api module, list of breaking changes:</h3>


  <table class="bodyTable">
    <tr>
      <th>Severity</th>
      <th>Description</th>
      <th>Class</th>
      <th>Method / Field</th>
    </tr>
    <tr >
      <td>Error</td>
      <td>Added final modifier to class</td>
      <td>org.slf4j.helpers.MessageFormatter</td>
      <td></td>
    </tr>
  </table>

  <p>Declaring <code>MessageFormatter</code> class as final should not
  affect users, unless they extend this class. However, since this
  class is intended to be used internally, very few users should be
  affected.
  </p>

  <h2><a href="#1_5_2" name="1_5_2">Version 1.5.2 compared to 1.5.1</a></h2>

  <p>No breaking changes to report.</p>

  <h2><a href="#1_5_1" name="1_5_1">Version 1.5.1 compared to 1.5.0</a></h2>


  <h3>slf4j-api module, list of breaking changes:</h3>


  <table class="bodyTable">
    <tr>
      <th>Severity</th>
      <th>Description</th>
      <th>Class</th>
      <th>Method / Field</th>
    </tr>
    <tr >
      <td>Error</td>
      <td>Method 'getCopyOfContextMap()' has been added to an
      interface
      </td>
      <td>org.slf4j.spi.MDCAdapter</td>
      <td>public java.util.Map getCopyOfContextMap()</td>
    </tr>
    <tr class="alt">
      <td>Error</td>
      <td>Method 'setContextMap(Map)' has been added to an
      interface
      </td>
      <td>org.slf4j.spi.MDCAdapter</td>
      <td>public void setContextMap(java.util.Map)</td>
    </tr>

    <tr>
      <td>Error</td>
      <td>Method 'getDetachedMarker(String)' has been added to an
      interface
      </td>
      <td>org.slf4j.IMarkerFactory</td>
      <td>public org.slf4j.Marker getDetachedMarker(java.lang.String)</td>
    </tr>

    <tr class="alt">
      <td>Info</td>
      <td>Method 'equals(Object)' has been added to an
      interface
      </td>
      <td>org.slf4j.Marker</td>
      <td>public boolean equals(java.lang.Object)</td>
    </tr>

    <tr>
      <td>info</td>
      <td>Method 'hashCode()' has been added to an
      interface
      </td>
      <td>org.slf4j.Marker</td>
      <td>public int hashCode()</td>
    </tr>

  </table>

  <p>The addition of the <code>getCopyOfContextMap()</code> method in
  the <code>MDCAdapter</code> class should only impact users who have
  their own implementation of the said interface. Except for bindings
  that ship with SLF4J and for logback-classic, which will be
  naturally upgraded, there are no known other implementations of
  <code>MDCAdapter</code>. In a rare but still possible scenario, if
  the user mixes different versions for slf4j-api.jar, say version
  1.5.1. and an SLF4J binding, say slf4j-log4j12.jar version 1.5.0,
  then a <code>java.lang.AbstractMethodError</code> will be thrown,
  but only if the client code calls the newly added method. <span
  style="color:green"> In short, although generally speaking the
  addition of a method to an interface is a breaking change, we are
  confident that no users will be impacted in this particular
  case.</span>
  </p>

  <p>Similar reasoning applies to the <code>setContextMap(Map)</code>
  method.</p>

  <p>The addition of <code>getDetachedMarker(String)</code> method in
  the <code>org.slf4j.IMarkerFactory</code> should not impact users as
  the only (known) implementation of this interface ships with SLF4J
  itself.
  </p>

  <p>The <code>equals()</code> and <code>hashCode()</code> methods
  were added to the <code>org.slf4j.Marker</code> interface for
  documentation purposes. Given that all objects implicitly implement
  these methods, their addition should theoretically not break
  existing code. </p>


  <h3>Other modules</h3>

  <p>No breaking changes to report.</p>


  <!-- ========================================= -->
  <h2><a href="#1_5_0" name="1_5_0">Version 1.5.0 compared to
  1.4.3</a></h2>

  <p>No breaking changes to report.</p>

  <!-- ========================================= -->
  <h2><a href="#1_4_3" name="1_4_3">Version 1.4.3 compared to
  1.4.2</a></h2>
  <p>No breaking changes to report.</p>

  <!-- ========================================= -->
  <h2><a href="#1_4_2" name="1_4_2">Version 1.4.2 compared to 1.4.1</a></h2>
  <p>No breaking changes to report.</p>

  <!-- ========================================= -->
  <h2><a href="#1_4_1" name="1_4_1">Version 1.4.1 compared to
  1.4.0</a></h2>
  <p>No breaking changes to report.</p>

</div> </body> </html>