Ignore:
Timestamp:
May 31, 2007, 9:33:52 AM (14 years ago)
Author:
Nicklas Nordborg
Message:

References #552, #553, #554: More information about backwards compatibility and Public vs. Internal
API.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/developerdoc/api_overview.xml

    r3409 r3415  
    5757        >javadoc</ulink> for information about
    5858      what parts of the API that contributes to the public API.
     59      Methods, classes and other elements that have been tagged as
     60      <code>@deprecated</code> should be considered as part of the internal API
     61      and may be removed in a subsequent relase without warning.
     62    </para>
     63   
     64    <para>
     65      See <xref linkend="appendix.incompatible" /> to read more about
     66      changes that have been introduced by each release.
    5967    </para>
    6068
     
    7078      </para>
    7179     
    72       <variablelist>
    73       <varlistentry>
    74         <term>Binary compatibility</term>
     80     
     81      <sect3 id="api_overview.compatibility.binary">
     82        <title>Binary compatibility</title>
     83        <para>
     84        <blockquote>
     85          Pre-existing Client binaries must link and run with new releases of the
     86          Component without recompiling.
     87        </blockquote>
     88       
     89        For example:
     90        <itemizedlist>
    7591        <listitem>
    7692          <para>
     93            We can't change the number or types of parameters to a method
     94            or constructor.
     95          </para>
     96        </listitem>
     97        <listitem>
     98          <para>
     99            We can't add or change methods to interfaces that are intended
     100            to be implemented by plug-in or client code.
     101          </para>
     102        </listitem>
     103        </itemizedlist>
     104        </para>       
     105      </sect3>
     106     
     107      <sect3 id="api_overview.compatibility.contract">
     108        <title>Contract compatibility</title>
     109        <para>
    77110          <blockquote>
    78             Pre-existing Client binaries must link and run with new releases of the
    79             Component without recompiling.
     111          API changes must not invalidate formerly legal Client code.
    80112          </blockquote>
    81          
     113       
    82114          For example:
    83115          <itemizedlist>
    84116          <listitem>
    85117            <para>
    86               We can't change the number or types of parameters to a method
    87               or constructor.
    88             </para>
    89           </listitem>
    90           <listitem>
    91             <para>
    92               We can't add or change methods to interfaces that are intended
    93               to be implemented by plug-in or client code.
     118              We can't change the implementation of a method to do
     119              things differently than before. For example, allow <constant>null</constant>
     120              as a return value when it wasn't allowed before.
    94121            </para>
    95122          </listitem>
    96123          </itemizedlist>
     124       
     125          <note>
     126            <para>
     127            Sometimes there is a very fine line between what is considered a
     128            bug and what is considered a feature. For example, if the
     129            actual implementation doesn't do what the javadoc says,
     130            do we change the code or do we change the documentation?
     131            This has to be considered from case to case and depends on
     132            the age of the code and if we expect plug-ins and clients to be
     133            affected by it or not.
     134            </para>
     135          </note>
     136        </para>
     137      </sect3>
     138     
     139      <sect3 id="api_overview.compatibility.source">
     140        <title>Source code compatibility</title>
     141        <para>
     142        This is not an important matter and is not always possible to
     143        achieve. In most cases, the problems are easy to fix.
     144        Example:
     145       
     146        <itemizedlist>
     147        <listitem>
     148          <para>
     149          Adding a class may break a plug-in or client that import
     150          classes with <constant>.*</constant> if the same class name
     151          exists in another package.
    97152          </para>
    98153        </listitem>
    99       </varlistentry>
    100       <varlistentry>
    101         <term>Contract compatibility</term>
    102         <listitem>
    103           <para>
    104             <blockquote>
    105             API changes must not invalidate formerly legal Client code.
    106             </blockquote>
    107          
    108             For example:
    109             <itemizedlist>
    110             <listitem>
    111               <para>
    112                 We can't change the implementation of a method to do
    113                 things differently than before. For example, allow <constant>null</constant>
    114                 as a return value when it wasn't allowed before.
    115               </para>
    116             </listitem>
    117             </itemizedlist>
    118          
    119             <note>
    120               <para>
    121               Sometimes there is a very fine line between what is considered a
    122               bug and what is considered a feature. For example, if the
    123               actual implementation doesn't do what the javadoc says,
    124               do we change the code or do we change the documentation?
    125               This has to be considered from case to case and depends on
    126               the age of the code and if we expect plug-ins and clients to be
    127               affected by it or not.
    128               </para>
    129             </note>
    130           </para>
    131         </listitem>
    132       </varlistentry>
    133       <varlistentry>
    134         <term>Source code compatibility</term>
    135         <listitem>
    136           <para>
    137           This is not an important matter and is not always possible to
    138           achieve. In most cases, the problems are easy to fix.
    139           Example:
    140          
    141           <itemizedlist>
    142           <listitem>
    143             <para>
    144             Adding a class may break a plug-in or client that import
    145             classes with <constant>.*</constant> if the same class name
    146             exists in another package.
    147             </para>
    148           </listitem>
    149           </itemizedlist>
    150           </para>
    151          
    152         </listitem>
    153       </varlistentry>
    154       </variablelist>
    155      
    156    
     154        </itemizedlist>
     155        </para>
     156      </sect3>
    157157    </sect2>
    158  
    159158  </sect1>
    160159
Note: See TracChangeset for help on using the changeset viewer.