Changeset 3409


Ignore:
Timestamp:
May 30, 2007, 3:35:40 PM (16 years ago)
Author:
Nicklas Nordborg
Message:

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

Location:
trunk
Files:
2 added
10 edited
1 moved

Legend:

Unmodified
Added
Removed

  • trunk/build.xml

    r3386 r3409  
    931931    name="doc.init"
    932932    >
     933    <property name="javadoc.src" location="doc/src/javadoc"
     934      description="Location of javadoc source files" />
    933935    <property name="docbook.src" location="doc/src/docbook"
    934936      description="Location of docbook source XML files" />
    … …  
    962964      private="true"
    963965      windowtitle="BASE ${base.version} API documentation"
    964       stylesheetfile="doc/javadoc.css"
     966      stylesheetfile="${javadoc.src}/javadoc.css"
    965967      classpathref="javadoc.classpath"
    966968      linksource="false"
    967969      breakiterator="yes"
    968970      encoding="iso-8859-1"
    969       >
     971      overview="${javadoc.src}/overview.html"
     972      >
     973      <group title="Public API"
     974        packages="net.sf.basedb.core:net.sf.basedb.core.plugin:net.sf.basedb.core.query:net.sf.basedb.util*:net.sf.basedb.clients.web.taglib*:net.sf.basedb.plugins:net.sf.basedb.core.authentication"
     975      />
     976      <group title="Mixed Public and Internal API"
     977        packages="net.sf.basedb.core.data:net.sf.basedb.clients.web:net.sf.basedb.clients.web.util"
     978      />
     979      <group title="Extension API"
     980        packages="net.sf.basedb.core.dbengine:net.sf.basedb.clients.jobagent"
     981      />
     982      <group title="Internal API"
     983        packages="net.sf.basedb.core.data.keyring:net.sf.basedb.clients.jobagent.*:net.sf.basedb.clients.migrate*:net.sf.basedb.clients.web.*"
     984      />
     985     
    970986      <header><![CDATA[${base.version}: ${TODAY}]]></header>
    971987      <link href="http://java.sun.com/j2se/1.5/docs/api"/>
    … …  
    977993      <link href="http://logging.apache.org/log4j/docs/api/" />
    978994      <link href="http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/" />
    979       <tag name="base.internal" description="Developer info" />
     995      <tag name="base.developer" description="Developer info" />
     996      <tag name="base.internal" description="This class/package is not part of the Public API" scope="overview,packages,types" />
    980997      <tag name="base.modified" description="Last modified" />
    981998      <tag name="hibernate.class" description="Hibernate: class" scope="types" />

  • trunk/doc/src/docbook/developerdoc/api_overview.xml

    r3315 r3409  
    2727-->
    2828
    29 <chapter id="api_overview" chunked="0">
     29<chapter id="api_overview">
    3030  <?dbhtml dir="api"?>
    3131  <title>API overview (how to use and code examples)</title>
     32
     33  <sect1 id="api_overview.public_api">
     34    <title>The Public API of BASE</title>
     35   
     36    <para>
     37      Not all public classes and methods in the <filename>BASE2Core.jar</filename>
     38      and other JAR files shipped with BASE are considered as
     39      <emphasis>Public API</emphasis>. This is important knowledge
     40      since we will always try to maintain backwards compatibility
     41      for classes that are part of the public API. For other
     42      classes, changes may be instroduced at any time without
     43      notice or specific documentation. In other words:
     44    </para>
     45   
     46    <note>
     47      <title>Only use the public API when developing plug-ins</title>
     48      <para>
     49        This will maximize the chance that you plug-in will continue
     50        to work with the next BASE release. If you use the non-public API
     51        you do so at your own risk.
     52      </para>
     53    </note>
     54   
     55    <para>
     56      See the <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
     57        >javadoc</ulink> for information about
     58      what parts of the API that contributes to the public API.
     59    </para>
     60
     61    <sect2 id="api_overview.compatibility">
     62      <title>What is backwards compatibility?</title>
     63     
     64      <para>
     65        There is a great article about this subject on <ulink
     66        url="http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs"
     67          >http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs</ulink>.
     68        This is what we will try to comply with. If you don't want to
     69        read the entire article, here are some of the most important points:
     70      </para>
     71     
     72      <variablelist>
     73      <varlistentry>
     74        <term>Binary compatibility</term>
     75        <listitem>
     76          <para>
     77          <blockquote>
     78            Pre-existing Client binaries must link and run with new releases of the
     79            Component without recompiling.
     80          </blockquote>
     81         
     82          For example:
     83          <itemizedlist>
     84          <listitem>
     85            <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.
     94            </para>
     95          </listitem>
     96          </itemizedlist>
     97          </para>
     98        </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   
     157    </sect2>
     158 
     159  </sect1>
    32160
    33161  <sect1 id="api_overview.data_api">

  • trunk/doc/src/docbook/developerdoc/core_ref.xml

    r3315 r3409  
    7676          >http://base.thep.lu.se/chrome/site/doc/development/coding/generic.html</ulink>
    7777      </para>
    78     </sect2>   
     78    </sect2>
     79 
    7980    <sect2 id="core_ref.rules.compatibility">
    8081      <title>API changes and backwards compatibility</title>
    8182      <para>
    82         TODO
    83       </para>
    84     </sect2>   
     83        The main rule is to don't introduce any changes that are
     84        backwards incompatible. That is, existing client applications
     85        and plug-ins should continue to run in the next release of BASE,
     86        without the need to change them. It may sound easy but there are
     87        many things to watch out for.
     88      </para>
     89     
     90      <para>
     91        There is a great article about this subject on <ulink
     92        url="http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs"
     93          >http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs</ulink>.
     94        This is what we will try to comply with.
     95      </para>
     96     
     97      <sect3 id="core_ref.rules.compatibility.public_api">
     98        <title>Does the changes affect the Public API?</title>
     99       
     100        <para>
     101          See <xref linkend="api_overview.public_api" /> and
     102          <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
     103          >the javadoc</ulink>for information
     104          about the public API.
     105        </para>
     106       
     107        <para>
     108          Changes made to the non-public API doesn't have to follow the
     109          same rules.
     110        </para>
     111      </sect3>
     112     
     113      <sect3 id="core_ref.rules.compatibility.contract">
     114        <title>Contract compatibility</title>
     115       
     116        <para>
     117          TODO
     118        </para>
     119       
     120      </sect3>
     121     
     122      <sect3 id="core_ref.rules.compatibility.binary">
     123        <title>Binary compatibility</title>
     124       
     125        <para>
     126          TODO
     127        </para>
     128       
     129      </sect3>
     130     
     131      <sect3 id="core_ref.rules.compatibility.data">
     132        <title>Internal data structure compatibility</title>
     133       
     134        <para>
     135          TODO
     136        </para>
     137       
     138      </sect3>
     139     
     140      <sect3 id="core_ref.rules.compatibility.source">
     141        <title>Source code compatibility</title>
     142       
     143        <para>
     144          TODO
     145        </para>
     146       
     147      </sect3>
     148     
     149    </sect2>
     150   
    85151    <sect2 id="core_ref.rules.datalayer">
    86152      <title>Data-layer rules</title>

  • trunk/doc/src/docbook/developerdoc/javadoc.xml

    r3315 r3409  
    3737  </para>
    3838 
     39  <para>
     40    See also <xref linkend="api_overview.public_api"/>
     41    for a discussion about what we consider to be the public part
     42    of the API.
     43  </para>
    3944
    4045</chapter>

  • trunk/lib/docbook/custom-styles/docbook/plain/css/docbook.css

    r3402 r3409  
    203203}
    204204
     205.blockquote {
     206  font-style: italic;
     207}
     208
    205209/* ------------------------------------------------------------------- }}} */
    206210

  • trunk/src/core/net/sf/basedb/core/Permission.java

    r2802 r3409  
    3030  This enumeration defined constants for permissions.
    3131 
    32   @base.internal
     32  @base.developer
    3333  Permissions are stored in the database as integers, which means that
    3434  a given set of permissions must be combined before they are saved.

  • trunk/src/core/net/sf/basedb/core/PluginDefinition.java

    r3078 r3409  
    459459    The name cannot be changed. Used internally only.
    460460
    461     @base.internal
     461    @base.developer
    462462    This value is initialised upon installation to: plugin.about().getName()
    463463    See: {@link #loadPluginInformation(String, String, boolean)}
    … …  
    491491    The description cannot be changed. Used internally only.
    492492
    493     @base.internal
     493    @base.developer
    494494    This value is initialised upon installation to: plugin.about().getDescription()
    495495    See: {@link #loadPluginInformation(String, String, boolean)}
    … …  
    513513    The version cannot be changed. Used internally only.
    514514
    515     @base.internal
     515    @base.developer
    516516    This value is initialised upon installation to: plugin.about().getVersion()
    517517    See: {@link #loadPluginInformation(String, String, boolean)}
    … …  
    535535    The copyright notice cannot be changed. Used internally only.
    536536
    537     @base.internal
     537    @base.developer
    538538    This value is initialised upon installation to: plugin.about().getCopyright()
    539539    See: {@link #loadPluginInformation(String, String, boolean)}
    … …  
    557557    The contact information cannot be changed. Used internally only.
    558558
    559     @base.internal
     559    @base.developer
    560560    This value is initialised upon installation to: plugin.about().getContact()
    561561    See: {@link #loadPluginInformation(String, String, boolean)}
    … …  
    579579    The email address cannot be changed. Used internally only.
    580580
    581     @base.internal
     581    @base.developer
    582582    This value is initialised upon installation to: plugin.about().getEmail()
    583583    See: {@link #loadPluginInformation(String, String, boolean)}
    … …  
    601601    The URL cannot be changed. Used internally only.
    602602
    603     @base.internal
     603    @base.developer
    604604    This value is initialised upon installation to: plugin.about().getUrl()
    605605    See: {@link #loadPluginInformation(String, String, boolean)}
    … …  
    673673    The type cannot be changed. Used internally only.
    674674
    675     @base.internal
     675    @base.developer
    676676    This value is initialised upon installation to: plugin.getMainType()
    677677    See: {@link #loadPluginInformation(String, String, boolean)}

  • trunk/src/core/net/sf/basedb/core/data/package.html

    r2304 r3409  
    5050</ul>
    5151
     52<p>
     53  @base.internal Except for the {@link net.sf.basedb.core.data.BatchableData}
     54  interface and classes implementing it.
     55</p>
     56
    5257</body>

  • trunk/src/core/net/sf/basedb/core/query/EntityQuery.java

    r2601 r3409  
    5151    Specify options for which items to include in the result.
    5252
    53     @base.internal
     53    @base.developer
    5454    These options are implemented as Hibernate filters. See
    5555    {@link net.sf.basedb.core.QueryRuntimeFilterFactory}
    … …  
    7070    Specify options for which items to exclude from the result.
    7171
    72     @base.internal
     72    @base.developer
    7373    These options are implemented as Hibernate filters. See
    7474    {@link net.sf.basedb.core.QueryRuntimeFilterFactory}

  • trunk/src/core/net/sf/basedb/core/query/HqlQuery.java

    r2304 r3409  
    4040    Specify if the query results should be cached or not.
    4141   
    42     @base.internal
     42    @base.developer
    4343    This option requires that a secondary cache that supports query results
    4444    are used (ie. EHCache).
Note: See TracChangeset for help on using the changeset viewer.