source: trunk/doc/src/docbook/developerdoc/core_ref.xml @ 5656

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: core_ref.xml 5656 2011-06-15 10:11:52Z nicklas $

  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson

  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/

  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.

  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="core_ref">
  <?dbhtml dir="core_ref"?>
  <title>Core developer reference</title>

  <sect1 id="core_ref.release">
    <title>Publishing a new release</title>
    <para>
      This documentation is available on the <ulink url="http://base.thep.lu.se/wiki/ReleaseProcedure">BASE wiki</ulink>.
    </para>
  </sect1>
  
  <sect1 id="core_ref.build">
    <title>Subversion / building BASE</title>
    <para>
      This documentation is available on the <ulink url="http://base.thep.lu.se/wiki/BuildingBase">BASE wiki</ulink>.
    </para>
  </sect1>

  <sect1 id="core_ref.rules" chunked="1">
    <title>Coding rules and guidelines</title>
    
    <sect2 id="core_ref.rules.devprocess">
      <title>Development process and other important procedures</title>
      <para>
         This section describes the development process we try to use in the BASE project. 
         It is not carved in stone and deviations may occur. For every new feature
         or enhancement the procure below should be followed.
         If you encounter any problems, arrange a group meeting. Someone else 
         may have the solution! The text is biased towards adding new
         items to BASE, but it should be possible to use the general outline
         even for other types of features.
      </para>
      
      <bridgehead>1. Group meeting</bridgehead>
      <itemizedlist>
      <listitem>
        <para>
        The group should have a short meeting and discuss the new or changed 
        feature. Problem areas should be identified, not solved!
        </para>
      </listitem>
      <listitem>
        <para>
        The person who is going to make the analysis, design and development is 
        responsible for taking notes. They should be kept until the analysis 
        and design phase has been finished.     
        </para>
      </listitem>
      <listitem>
        <para>
        A follow-up meeting should be held at the end of the analysis phase.  
        </para>
      </listitem>
      <listitem>
        <para>
        A single meeting may of course discuss more than one feature.
        </para>
      </listitem>
      </itemizedlist>
      
      <bridgehead>2. Analysis and design</bridgehead>
      <itemizedlist>
      <listitem>
        <para>
        Create an diagram of the classes including their properties, links and associations. 
        Use the already existing diagrams and code as a template.
        The diagram should have information about cache and proxy settings.
        </para>
      </listitem>
      <listitem>
        <para>
        Write a short document about the diagram, especially things that are not obvious 
        and explain any deviations from the recommendations in the coding guidelines.
        </para>
      </listitem>
      <listitem>
        <para>
        Identify things that may affect backwards compatibility. For more 
        information about such things read <xref linkend="api_overview.public_api" />
        and <xref linkend="core_ref.rules.compatibility" />.
        </para>
      </listitem>
      <listitem>
        <para>
        Identify what parts of the documentation that needs to changed or added
        to describe the new feature. This includes, but is not limited to:
        <itemizedlist>
        <listitem>
          <para>
          User and administrator documentation, how to use the feature, screenshots, 
          etc.
          </para> 
        </listitem>
        <listitem>
          <para>
          Plug-in and core developer documentation, code examples, database schema changes,
          etc.
          </para> 
        </listitem>
        </itemizedlist>
        </para>
      </listitem>
      <listitem>
        <para>
        If there are any problems with the existing code, these should be solved at 
        this stage. Write some prototype code for testing if necessary.
        </para>
      </listitem>
      <listitem>
        <para>
        Group meeting to verify that the specified solution is ok, and to make sure 
        everybody has enough knowledge of the solution.
        </para>
      </listitem>
      </itemizedlist>
      
      <bridgehead>3. Create the classes for the data layer</bridgehead>
      <itemizedlist>
      <listitem>
        <para>
        If step 2 is properly done, this should not take long.
        </para>
      </listitem>
      <listitem>
        <para>
        Follow the coding guidelines in <xref linkend="core_ref.rules.datalayer" />.
        </para>
      </listitem>
      <listitem>
        <para>
        At the end of this step, go back and have a lock at the diagram/documentation 
        from the analysis and design phase and make sure everything is still correct.
        </para>
      </listitem>
      </itemizedlist>
      
      <bridgehead>4. Create the corresponding classes in the core layer</bridgehead>
      <itemizedlist>
      <listitem>
        <para>
        For simple cases this is also easy. Other cases may require more effort.
        </para>
      </listitem>
      <listitem>
        <para>
        If needed, go back to the analysis and design phase and do some more investigations. 
        Make sure the documentation is updated if there are changes.
        </para>
      </listitem>
      </itemizedlist>
      
      <bridgehead>5. Create test code</bridgehead>
      <itemizedlist>
      <listitem>
        <para>
        Build on and use the existing test as much as possible.
        </para>
      </listitem>
      </itemizedlist>
      
      <bridgehead>6. Write code to update existing installations</bridgehead>
      <important>
      <itemizedlist>
      <listitem>
        <para>
        If the database schema is changed or if there for some reason is need to update
        existing data in the database, the <constant>Install.SCHEMA_VERSION</constant>
        counter must be increased.
        </para>
      </listitem>
      <listitem>
        <para>
        Add code to the <classname docapi="net.sf.basedb.core">net.sf.basedb.core.Update</classname> class
        to increase the schema version and modify data in existing installations.
        </para>
      </listitem>
      </itemizedlist>
      </important>
      
      <bridgehead>7. Write new and update existing user documentation</bridgehead>
      <itemizedlist>
      <listitem>
        <para>
        Most likely, users and plug-in developers wants to know about the feature.
        </para>
      </listitem>
      </itemizedlist>

      <important>
      <para>
      Do not forget to update the <xref linkend="appendix.incompatible" /> document
      if you have introduced any incomaptible changes.
      </para>
      </important>
      
    </sect2>
    <sect2 id="core_ref.rules.style">
      <title>General coding style guidelines</title>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/development/coding/generic.html"
          >http://base.thep.lu.se/chrome/site/doc/historical/development/coding/generic.html</ulink>
      </para>
    </sect2>
  
    <sect2 id="core_ref.rules.compatibility">
      <title>API changes and backwards compatibility</title>
      <para>
        The main rule is to do not introduce any changes that are
        backwards incompatible. That is, existing client applications 
        and plug-ins should continue to run in the next release of BASE,
        without the need to change them. It may sound easy but there are
        many things to watch out for.
      </para>
      
      <important>
        <title>Do not forget to log changes!</title>
        <para>
        Any change that may affect backwards compatibility must be logged in
        <xref linkend="appendix.incompatible" />.
        </para>
      </important>
      
      <para>
        There is a great article about this subject on <ulink 
        url="http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs"
          >http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs</ulink>.
        This is what we will try to comply with.
      </para>
      
      <sect3 id="core_ref.rules.compatibility.public_api">
        <title>Does the changes affect the Public API?</title>
        
        <para>
          See <xref linkend="api_overview.public_api" /> and
          <ulink url="http://base.thep.lu.se/chrome/site/doc/api/index.html"
          >the javadoc</ulink>for information
          about the public API.
        </para>
        
        <para>
          Changes made to the non-public API does not have to follow the
          same rules.
        </para>
      </sect3>
      
      <sect3 id="core_ref.rules.compatibility.contract">
        <title>Contract compatibility</title>
        
        <para>
          TODO
        </para>
        
      </sect3>
      
      <sect3 id="core_ref.rules.compatibility.binary">
        <title>Binary compatibility</title>
        
        <para>
          TODO
        </para>
        
      </sect3>
      
      <sect3 id="core_ref.rules.compatibility.data">
        <title>Internal data structure compatibility</title>
        
        <para>
          TODO
        </para>
        
      </sect3>
      
      <sect3 id="core_ref.rules.compatibility.source">
        <title>Source code compatibility</title>
        
        <para>
          TODO
        </para>
        
      </sect3>
      
    </sect2>
    
    <sect2 id="core_ref.rules.datalayer">
      <title>Data-layer rules</title>

      <para>
        The coding guidelines for this package has been slightly modified from the 
        the general coding guidelines. Here is a short list with the changes.
      </para>
      
      <sect3 id="core_ref.rules.datalayer.methodorder">
        <title>Attributes and methods order</title>
        <para>
          Inside a class, attributes and methods should be organised in related groups, 
          ie. the private attribute is together with the getter and setter methods that uses 
          that attribute. This makes it easy to re-use existing code with copy-and-paste
          operations.
        </para>
          
        <programlisting language="java">
public static int long MAX_ADDRESS_LENGTH = 255;
private String address;
/**
   @hibernate.property column="`address`" type="string" length="255" not-null="false"
*/
public String getAddress()
{
   return address;
}
public void setAddress(String address)
{
   this.address = address;
}

private int row;
/**
   @hibernate.property column="`row`" type="int"
*/
public int getRow()
{
   return row;
}
public void setRow(int row)
{
   this.row = row;
}       
</programlisting>
        </sect3>
        
        <sect3 id="core_ref.rules.datalayer.classnames">
          <title>Class and interface names</title>
        <para>
          Class names should follow the general guidelines, but should in most
          cases end with <classname>Data</classname>.
        </para>
        <programlisting language="java">
public class SampleData
   extends CommonData
   implements DiskConsumableData
{
   ...
}
</programlisting>
      </sect3>
      <sect3 id="core_ref.rules.datalayer.basicclasses">
        <title>Extend/implement the basic classes and interfaces</title>
        <para>
          Each data-class must inherit from one of the already existing abstract base classes. 
          They contain code that is common to all classes, for example implementations of 
          the <methodname>equals()</methodname> and <methodname>hashCode()</methodname>
          methods or how to link with the owner of an item. For information about
          which classes/interfaces that can be used see <xref linkend="data_api.basic" />.
        </para>
      </sect3>

      <sect3 id="core_ref.rules.datalayer.constructor">
        <title>Define a public no-argument constructor</title>
        <para>
          Always define a public a no-argument constructor. No other constructors are needed. 
          If we want to use other persistence mechanisms or serializability in the future 
          this type of constructor is probably the most compatible. The constructor should 
          be empty and not contain any code. Do not initialise properties or create new objects 
          for internal use. Most of the time the object is loaded by 
          Hibernate and Hibernate will ensure that it is properly initialised by calling 
          all setter methods.
        </para>

        <para>
          For example, a many-to-many relation usually has a <interfacename>Set</interfacename>
          or a <interfacename>Map</interfacename> to hold the links to the other objects. Do not 
          create a new <classname>HashSet</classname> or <classname>HashMap</classname>
          in the constructor. Wait until the get method is called and only create a new 
          object if Hibernate hasn't already called the setter method with it's own object. 
          See the code example below. There is also more information about this in 
          <xref linkend="core_ref.rules.datalayer.manytomany" />.
        </para>
        
        <programlisting language="java">
// From GroupData.java
public GroupData() 
{}

private Set&lt;UserData&gt; users;
public Set&lt;UserData&gt; getUsers()
{
   if (users == null) users = new HashSet&lt;UserData&gt;();
   return users;
}
</programlisting>

        <para>
        See also:
        </para>
        
        <itemizedlist>
        <listitem>
          <para>
          "Hibernate in action", chapter 3.2.3 "Writing POJOs", page 67-69
          </para>
        </listitem>
        <listitem>
          <para>
          Hibernate user documentation: <ulink 
            url="http://www.hibernate.org/hib_docs/reference/en/html/persistent-classes.html#persistent-classes-pojo-constructor">4.1.1. 
            Implement a no-argument constructor</ulink>
          </para>
        </listitem>
        </itemizedlist>

      </sect3>

      <sect3 id="core_ref.rules.datalayer.identity">
        <title>Object identity</title>
        <para>
          We use database identity to compare objects, ie. two objects are considered 
          equal if they are of the same class and have the same id, thus representing the 
          same database row. All this stuff is implemented by the BasicData class. Therefore 
          it is required that all classes are subclasses of this class. It is recommended 
          that the <methodname>equals()</methodname> or <methodname>hashCode()</methodname>
          methods are not overridden by any of the subclasses. We would have liked to make 
          them final, but then the proxy feature of Hibernate would not work.
        </para>
        
        <warning>
          <title>Avoid mixing saved and unsaved objects</title>
          <para>
            The approch used for object identity may give us a problem if we mix objects
            which hasn't been saved to the database, with objects loaded from the database. 
            Our recommendation is to avoid that, and save any objects to the database before 
            adding them to sets, maps or any other structure that uses the 
            <methodname>equals()</methodname> and <methodname>hashCode()</methodname> methods.
          </para>
          <para>
            To be more specific, the problem arises because the following two rules for 
            hascodes are contradicting when the hashcode is based on the database id:
          </para>
          <orderedlist>
          <listitem>
            <para>
            The hash code of an object mustn't change
            </para>
          </listitem>
          <listitem>
            <para>
            Equal objects must have equal hash code
            </para>
          </listitem>
          </orderedlist>
          <para>
            For objects in the database, the hash code is based on the id. For new objects, 
            which doesn't have an id yet, we fall back to the system hash code. But, what 
            happens when we save the new object to the database? If nobody has asked for 
            the hash code it is safe to use the id, otherwise we must stick with the system 
            hash code. Now, imagine that we load the same object from the database in 
            another Hibernate session. What will now happen? The loaded object will have 
            it's hash code based on the id but the original object is still using the
            system hash code, which most likely is not the same as the id. Yet, the 
            <methodname>equals()</methodname> method returns true. This is a violation 
            of the contract for the equals method. If these two objects are used in a set 
            it may cause unexpected behaviour. Therefore, do not put new objects in a 
            set, or other collection, that calls the <methodname>hashCode()</methodname> 
            method before the object is saved to the database.          
          </para>
        </warning>
        
        <para>
        See also:
        </para>
        <itemizedlist>
        <listitem>
          <para>
          "Hibernate in action", chapter 3.4 "Understanding object identity", page 87-90
          </para>
        </listitem>
        <listitem>
          <para>
          "Hibernate in action", chapter 4.1.4 "The scope of object identity", page 119-121
          </para>
        </listitem>
        <listitem>
          <para>
          "Hibernate in action", chapter 4.1.6 "Implementing equals() and hashCode(), page 122-126
          </para>
        </listitem>
        <listitem>
          <para>
          Hibernate user documentation: <ulink 
            url="http://www.hibernate.org/hib_docs/reference/en/html/persistent-classes.html#persistent-classes-equalshashcode">4.3. Implementing equals() and hashCode()</ulink>
          </para>
        </listitem>
        </itemizedlist>
      </sect3>

      <sect3 id="core_ref.rules.datalayer.nofinal">
        <title>No final methods</title>
        <para>
          No methods should be tagged with the <constant>final</constant> keyword. This is a 
          requirement to be able to use the proxy feature of Hibernate, which we need for 
          performance reasons.
        </para>

        <para>
        See also:
        </para>
        <itemizedlist>
        <listitem>
          <para>
          Hibernate user documentation: <ulink 
            url="http://www.hibernate.org/hib_docs/reference/en/html/persistent-classes.html#persistent-classes-pojo-final">4.1.3. Prefer non-final classes</ulink>
          </para>
        </listitem>
        <listitem>
          <para>
          Hibernate user documentation: <ulink 
            url="http://www.hibernate.org/hib_docs/reference/en/html/performance.html#performance-fetching-proxies">19.1.3. Single-ended association proxies</ulink>
          </para>
        </listitem>
        </itemizedlist>

      </sect3>

      <sect3 id="core_ref.rules.datalayer.cache">
        <title>Second-level cache</title>
        <para>
          To gain performance we use the second-level cache of Hibernate. It is a transparent
          feature that doesn't affect the code in any way. The second-level cache is configured 
          in the <filename>hibernate.cfg.xml</filename> and <filename>ehcache.xml</filename> 
          files and not in the individual class mapping files. BASE is shipped with a standard
          configuration, but different deployment scenarios may have to fine-tune the cache 
          settings for that particular hardware/software setup. It is beyond the scope of 
          this document to discuss this issue.
        </para>
        
        <para>
          The second-level cache is suitable for objects that are rarely modified but 
          are often needed. For example, we do not expect the user information represented 
          by the <classname docapi="net.sf.basedb.core.data">UserData</classname> object to change very often, but it is 
          displayed all the time as the owner of various items.
        </para>
        
        <para>
          It is required that one thinks a bit of the usage of a class before coming 
          up with a good caching strategy. We have to answer the following questions:
        </para>
        
        <orderedlist>
        <listitem>
          <para>
          Should objects of this class be cached at all?
          </para>
        </listitem>
        <listitem>
          <para>
          How long timeout should we use?
          </para>
        </listitem>
        <listitem>
          <para>
          How many objects should we keep in memory or on disk?
          </para>
        </listitem>
        </orderedlist>
        
        <para>
          The first question is the most important. Good candidates are classes with few 
          objects that change rarely, but are read often. Also, objects which are linked 
          to by many other objects are good candidates. The <classname docapi="net.sf.basedb.core.data">UserData</classname>
          class is an example which matches all three requirements. The <classname docapi="net.sf.basedb.core.data">LabelData</classname>
          class is an example which fulfils the first two. The <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
          class is on the other hand a bad cache candidate, since it is not linked to any 
          other object than a <classname docapi="net.sf.basedb.core.data">BioMaterialData</classname> object.
        </para>
        
        <para>
          The answer to the second question depends on how often an object is modified. 
          For most objects this time is probably several days or months, but we would 
          not gain much by keeping objects in the cache for so long. Suddenly, the 
          information has changed and we won't risk that old information is kept that 
          long. We have set the timeout to 1 hour for all classes so far, and we don't 
          recommend a longer timeout. The only exception is for immutable objects, that 
          cannot be changed at all, which may have an infinite timeout.
        </para>
        
        <para>
          The answer to the third question depends a lot on the hardware (available memory).
          With lots of memory we can afford to cache more objects. Caching to disk is not 
          really necessary if the database is on the same machine as the web server, but 
          if it is on another machine we have to consider the network delay to connect 
          to the database versus the disk access time. The default configuration does not 
          use disk cache.
        </para>

        <para>
        See also:
        </para>
        <itemizedlist>
        <listitem>
          <para>
          "Hibernate in action", chapter 5.3 "Caching theory and practice", page 175-194.
          </para>
        </listitem>
        <listitem>
          <para>
          Hibernate user documentation: <ulink 
            url="http://www.hibernate.org/hib_docs/reference/en/html/performance.html#performance-cache">19.2. The Second Level Cache</ulink>
          </para>
        </listitem>
        </itemizedlist>

      </sect3>

      <sect3 id="core_ref.rules.datalayer.proxies">
        <title>Proxies</title>
        
        <para>
          Proxies are also used to gain performance, and they may have some impact on 
          the code. Proxies are created at runtime (by Hibernate) as a subclass of the 
          actual class but are not populated with data until some method of the object 
          is called. The data is loaded from the database the first time a method other 
          than <methodname>getId()</methodname> is called. Thus, we can avoid loading 
          data that is not needed at a particular time.
        </para>
        
        <para>
          There can be a problem with using the <code>instanceof</code> operator with proxies 
          and the table-per-class-hierarchy mapping. For example, if we have the abstract 
          class <classname>Animal</classname> and subclasses <classname>Cat</classname>
          and <classname>Dog</classname>. The proxy of an <classname>Animal</classname> is a 
          runtime generated subclass of <classname>Animal</classname>, since we do not know if it 
          is a <classname>Cat</classname> or <classname>Dog</classname>. So, 
          <code>x instanceof Dog</code> and <code>x instanceof Cat</code> would both return 
          false. If we hadn't used a proxy, at least one of them would always be true.
        </para>
        
        <para>
          Proxies are only used when a not-null object is linked with many-to-one or 
          one-to-one from another object. If we ask for a specific object by id, or by a 
          query, we will never get a proxy. Therefore, it only makes sense to enable 
          proxies for classes that can be linked from other classes. One-to-one links on 
          the primary key where null is allowed silently disables the proxy feature, 
          since Hibernate doesn't know if there is an object or not without querying 
          the database.
        </para>
        
        <bridgehead>Proxy vs. cache</bridgehead>
        <para>
          The goal of a proxy and the second-level cache are the same: to avoid hitting the 
          database. It is perfectly possible to enable both proxies and the cache for a 
          class. Then we would start with a proxy and as soon as a method is called Hibernate 
          would look in the second-level cache. Only if it is not there it would be loaded 
          from the database. But, do we really need a proxy in the first place? Well, I think 
          it might be better to use only the cache or only proxies. But, this also makes it 
          even more important that the cache is configured correctly so there is a high 
          probability that the object is already in the cache.
        </para>
        
        <para>
          If a class has been configured to use the second-level cache, we recommend 
          that proxies are disabled. For child objects in a parent-child relationship proxies 
          should be disabled, since they have no other links to them than from the parent. 
          If a class can be linked as many-to-one from several other classes it makes sense 
          to enable proxies. If we have a long chain of many-to-one relations it may also make 
          sense to enable proxies at some level, even if the second-level cache is used. 
          In that case we only need to create one proxy instead of looking up several objects 
          in the cache. Also, think about how a particular class most commonly will be used 
          in a client application. For example, it is very common to display the name of the 
          owner of an item, but we are probably not interested in displaying quota 
          information for that user. So, it makes sense to put users in the second-level 
          cache and use proxies for quota information.
        </para>
        
        <warning>
          <title>Batchable classes and stateless sessions</title>
          <para>
            Starting with Hibernate 3.1 there is a new stateless session feature. A 
            stateless session has no first-level cache and doesn't use the second-level 
            cache either. This means that if we load an item with a stateless session 
            Hibernate will always traverse many-to-one and one-to-one associations and 
            load those objects as well, unless they are configured to use proxies.
          </para>
          
          <para>
            Stateless sessions are used by batchable items (reporters, raw data and features) 
            since they are many and we want to use as little memory as possible. Here it 
            is required that proxies are enabled for all items that are linked from any of 
            the batchable items, ie. <classname docapi="net.sf.basedb.core">RawBioAssay</classname>, 
            <classname docapi="net.sf.basedb.core">ReporterType</classname>, 
            <classname docapi="net.sf.basedb.core">ArrayDesignBlock</classname>, etc.
            If we don't do this Hibernate will generate multiple additional select
            statements for the same parent item which will affect performance 
            in a bad way.
          </para>
          
          <para>
            On the other hand, the proxies created from a stateless session cannot later 
            be initialised. We have to get the ID from the proxy and the load the object 
            using the regular session. But this can also results in lots of additional select
            statements so if it is known before that we need some information it is recommended
            that a FETCH JOIN is used so that we get fully initialized objects instead of
            proxies to begin with.
          </para>
        </warning>
        
        <para>
          Here is a table which summarises different settings for the second-level cache, 
          proxies, batch fetching and many-to-one links. Batch fetching and many-to-one links 
          are discussed later in this document.
        </para>
        
        <para>
          First, decide if the second-level cache should be enabled or not. Then, if 
          proxies should be enabled or not. The table then gives a reasonable setting for 
          the batch size and many-to-one mappings. NOTE! The many-to-one mappings are 
          the links from other classes to this one, not links from this class.
        </para>
        
        <para>
          The settings in this table are not absolute rules. In some cases there might 
          be a good reason for another combination. Please, write a comment about why 
          the recommendations were not followed.
        </para>
        
        <table id="core_ref.rules.datalayer.cacheproxysettings">
          <title>Choosing cache and proxy settings</title>
          <tgroup cols="4">
            <colspec colname="cache" />
            <colspec colname="proxy" />
            <colspec colname="batchsize" />
            <colspec colname="outerjoin" />
            
            <thead>
              <row>
                <entry>Global configuration</entry>
                <entry namest="proxy" nameend="batchsize">Class mapping</entry>
                <entry>Many-to-one mapping</entry>
              </row>
              <row>
                <entry>Cache</entry>
                <entry>Proxy</entry>
                <entry>Batch-size</entry>
                <entry>Outer-join</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>no</entry>
                <entry>no*</entry>
                <entry>yes</entry>
                <entry>true</entry>
              </row>
              <row>
                <entry>yes</entry>
                <entry>no*</entry>
                <entry>no</entry>
                <entry>false</entry>
              </row>
              <row>
                <entry>no</entry>
                <entry>yes</entry>
                <entry>yes</entry>
                <entry>false</entry>
              </row>
              <row>
                <entry>yes</entry>
                <entry>yes</entry>
                <entry>no</entry>
                <entry>false</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        
        <para>
          * = Do not use this setting for classes which are many-to-one linked from a batchable 
          class.
        </para>
        
        <para>
        See also:
        </para>
        <itemizedlist>
        <listitem>
          <para>
          "Hibernate in action", chapter 4.4.6 "Selecting a fetching strategy in mappings", page 146-147
          </para>
        </listitem>
        <listitem>
          <para>
          "Hibernate in action", chapter 6.4.1 "Polymorphic many-to-one associations", page 234-236
          </para>
        </listitem>
        <listitem>
          <para>
          Hibernate user documentation: <ulink 
            url="http://www.hibernate.org/hib_docs/reference/en/html/performance.html#performance-fetching-proxies">19.1.3. Single-ended association proxies</ulink>
          </para>
        </listitem>
        </itemizedlist>
        
      </sect3>
      
      <sect3 id="core_ref.rules.datalayer.hibernate">
        <title>Hibernate mappings</title>
        
        <para>
          We use Javadoc tags to specify the database mapping needed by Hibernate.
          The tags are processed by XDoclet at build time which generates the XML-based 
          Hibernate mapping files.
        </para>
        
        <note>
          <title>XDoclet doesn't support all mappings</title>
          <para>
          The XDoclet that we use was developed to generate mapping files for
          Hibernate 2.x. Since then, Hibernate has released several 3.x versions,
          and the mapping file structure has changed. Some changes can be handled by
          generating a corresponding 2.x mapping and then converting it to a 3.x
          mapping at build time using simple search-and-replace operations.
          One such case is to update the DTD reference to the 3.0 version instead of 
          the 2.0 version. Other changes can't use this approach. Instead we have to
          provide extra mappings inside an XML files. This is also needed if we need
          to use some of the new 3.x features that has no 2.x counterpart.
          </para>
        </note>
        
        <simplesect id="core_ref.rules.datalayer.class">
          <title>Class mapping</title>
          
          <programlisting language="java">
/**
   This class holds information about any data...
   @author Your name
   @version 2.0
   @hibernate.class table="`Anys`" lazy="false" batch-size="10"
   @base.modified $Date: 2007-08-17 09:18:29 +0200 (Fri, 17 Aug 2007) $
*/
public class AnyData
   extends CommonData
{
   // Rest of class code...
}
</programlisting>
          
          <para>
            The class declaration must contain a <code>@hibernate.class</code> Javadoc entry 
            where Hibernate can find the name of the table where items of this type are stored. 
            The table name should generally be the same as the class name, without the ending 
            <code>Data</code> and in a plural form. For example <classname docapi="net.sf.basedb.core.data">UserData</classname>
            --&gt; <code>Users</code>. The back-ticks (`) around the table name tells Hibernate
            to enclose the name in whatever the actual database manager uses for such things 
            (back-ticks in MySQL, quotes for an ANSI-compatible database).
          </para>
          
          <important>
            <title>Specify a value for the lazy attribute</title>
            <para>
              The lazy attribute enables/disables proxies for the class. Do not forget 
              to specify this attribute since the default value is true. If proxies are 
              enabled, it may also make sense to specify a batch-size attribute. Then 
              Hibernate will load the specified number of items in each SELECT statement
              instead of loading them one by one. It may also make sense to specify a 
              batch size when proxies are disabled, but then it would probably be even 
              better to use eager fetching by setting <code>outer-join="true"</code>
              (see many-to-one mapping).
            </para>

            <para>
              Classes that are linked with a many-to-one association from a batchable 
              class must specify <code>lazy="true"</code>. Otherwise the stateless session
              feature of Hibernate may result in a large number of SELECT:s for the same 
              item, or even circular loops if two or more items references each other.
            </para>
          </important>
          
          <important>
            <title>Remember to enable the second-level cache</title>
            <para>
              Do not forget to configure settings for the second-level cache if this
              should be enabled. This is done in the <filename>hibernate.cfg.xml</filename>
              and <filename>ehcache.xml</filename>.
            </para>
          </important>
        
          <para>
          See also:
          </para>
          
          <itemizedlist>
          <listitem>
            <para>
            "Hibernate in action", chapter 3.3 "Defining the mapping metadata", page 75-87
            </para>
          </listitem>
          <listitem>
            <para>
            Hibernate user documentation: <ulink 
              url="http://www.hibernate.org/hib_docs/reference/en/html/mapping.html#mapping-declaration-class">5.1.3. class</ulink>
            </para>
          </listitem>
          </itemizedlist>
          
        </simplesect>
        
        <simplesect id="core_ref.rules.datalayer.property">
          <title>Property mappings</title>
          
          <para>
            Properties such as strings, integers, dates, etc. are mapped with
            the <code>@hibernate.property</code> Javadoc tag. The main purpose 
            is to define the database column name. The column names should
            generally be the same as the get/set method name without the get/set prefix, 
            and with upper-case letters converted to lower-case and an underscore inserted. 
            Examples:
          </para>
          
          <itemizedlist>
          <listitem>
            <para>
              <methodname>getAddress()</methodname>
              --&gt; <code>column="`address`"</code>
            </para>
          </listitem>
          <listitem>
            <para>
              <methodname>getLoginComment()</methodname>
              --&gt; <code>column="`login_comment`"</code>
            </para>
          </listitem>
          </itemizedlist>
          
          <para>
            The back-ticks (`) around the column name tells Hibernate to enclose 
            the name in whatever the actual database manager uses for such things 
            (back-ticks in MySQL, quotes for an ANSI-compatible database).
          </para>
          
          <bridgehead>String properties</bridgehead>
          
          <programlisting language="java">
public static int long MAX_STRINGPROPERTY_LENGTH = 255;
private String stringProperty;
/**
   Get the string property.
   @hibernate.property column="`string_property`" type="string" 
      length="255" not-null="true"
*/
public String getStringProperty()
{
   return stringProperty;
}
public void setStringProperty(String stringProperty)
{
   this.stringProperty = stringProperty;
}
</programlisting>

          <para>
            Do not use a greater value than 255 for the length attribute. Some databases 
            has that as the maximum length for character columns (ie. MySQL). If you need 
            to store longer texts use <code>type="text"</code> instead. You can then skip 
            the length attribute. Most databases will allow up to 65535 characters or more 
            in a text field. Do not forget to specify the <code>not-null</code> attribute.
          </para>
          
          <para>
            You should also define a public constant <constant>MAX_STRINGPROPERTY_LENGTH</constant>
            containing the maximum allowed length of the string.
          </para>
          
          <bridgehead>Numerical properties</bridgehead>
          
          <programlisting language="java">
private int intProperty;
/**
   Get the int property.
   @hibernate.property column="`int_property`" type="int" not-null="true"
*/
public int getIntProperty()
{
   return intProperty;
}
public void setIntProperty(int intProperty)
{
   this.intProperty = intProperty;
}
</programlisting>

          <para>
            It is also possible to use <classname>Integer</classname>, <classname>Long</classname>
            or <classname>Float</classname> objects instead of <classname>int</classname>,
            <classname>long</classname> and <classname>float</classname>. We have only used it 
            if null values have some meaning.
          </para>

        <bridgehead>Boolean properties</bridgehead>
        <programlisting language="java">
private boolean booleanProperty;
/**
   Get the boolean property.
   @hibernate.property column="`boolean_property`" 
      type="boolean" not-null="true"
*/
public boolean isBooleanProperty()
{
   return booleanProperty;
}
public void setBooleanProperty(boolean booleanProperty)
{
   this.booleanProperty = booleanProperty;
}
</programlisting>
        <para>
          It is also possible to use a <classname>Boolean</classname> object instead of
          <classname>boolean</classname>. It is only required if you absolutely need 
          null values to handle special cases.
        </para>
        
        <bridgehead>Date values</bridgehead>
        
        <programlisting language="java">
private Date dateProperty;
/**
   Get the date property. Null is allowed.
   @hibernate.property column="`date_property`" type="date" not-null="false"
*/
public Date getDateProperty()
{
   return dateProperty;
}
public void setDateProperty(Date dateProperty)
{
   this.dateProperty = dateProperty;
}
</programlisting>
        
        <para>
          Hibernate defines several other date and time types. We have decided to use
          the <code>type="date"</code> type when we are only interested in the date and 
          the <code>type="timestamp"</code> when we are interested in both the date 
          and time.
        </para>
        
        <para>
        See also: 
        </para>
        
        <itemizedlist>
          <listitem>
            <para>
            "Hibernate in action", chapter 3.3.2 "Basic property and class mappings", page 78-84
            </para>
          </listitem>
          <listitem>
            <para>
            "Hibernate in action", chapter 6.1.1 "Built-in mapping types", page 198-200
            </para>
          </listitem>
          <listitem>
            <para>
            Hibernate user documentation: <ulink 
              url="http://www.hibernate.org/hib_docs/reference/en/html/mapping.html#mapping-declaration-property">5.1.9. property</ulink>
            </para>
          </listitem>
          <listitem>
            <para>
            Hibernate user documentation: <ulink 
              url="http://www.hibernate.org/hib_docs/reference/en/html/mapping.html#mapping-types-basictypes">5.2.2. Basic value types</ulink>
            </para>
          </listitem>
          </itemizedlist>
          
        </simplesect>
        
        <simplesect id="core_ref.rules.datalayer.manytoone">
          <title>Many-to-one mappings</title>
          
          <programlisting language="java">
private OtherData other;
/**
   Get the other object.
   @hibernate.many-to-one column="`other_id`" not-null="true" outer-join="false"
*/
public OtherData getOther()
{
   return other;
}
public void setOther(OtherData other)
{
   this.other = other;
}
</programlisting>
          
        <para>
          We create a many-to-one mapping with the <code>@hibernate.many-to-one</code> tag. 
          The most important attribute is the <code>column</code> attribute which specifies the name of 
          the database column to use for the id of the other item. The back-ticks (`) 
          around the column name tells Hibernate to enclose the name in whatever the 
          actual database manager uses for such things (back-ticks in MySQL, quotes for 
          an ANSI-compatible database).
        </para>
        
        <para>
          We also recommend that the <code>not-null</code> attribute is specified. Hibernate 
          will not check for null values, but it will generate table columns that allow 
          or disallow null values. See it as en extra safety feature while debugging. 
          It is also used to determine if Hibernate uses <code>LEFT JOIN</code> or 
          <code>INNER JOIN</code> in SQL statements.
        </para>
        
        <para>
          The <code>outer-join</code> attribute is important and affects how the 
          cache and proxies are used. It can take three values: <constant>auto</constant>,
          <constant>true</constant> or <constant>false</constant>. If the value is 
          <constant>true</constant> Hibernate will always use a join to load the linked 
          object in a single select statement, overriding the cache and proxy settings. 
          This value should only be used if the class being linked has disabled both 
          proxies and the second-level cache, or if it is a link between a child 
          and parent in a parent-child relationship. A false value is best when
          we expect the associated object to be in the second-level cache or proxying 
          is enabled. This is probably the most common case. The auto setting uses a 
          join if proxying is disabled otherwise it uses a proxy. Since we always 
          know if proxying is enabled or not, this setting is not very useful. See 
          <xref linkend="core_ref.rules.datalayer.cacheproxysettings" /> for the 
          recommended settings.
        </para>
        
        <para>
          See also:
        </para>
          
        <itemizedlist>
          <listitem>
            <para>
            "Hibernate in action", chapter 3.7 "Introducing associations", page 105-112
            </para>
          </listitem>
          <listitem>
            <para>
            "Hibernate in action", chapter 4.4.5-4.4.6 "Fetching strategies", page 143-151
            </para>
          </listitem>
          <listitem>
            <para>
            "Hibernate in action", chapter 6.4.1 "Polymorphic many-to-one associations", page 234-236
            </para>
          </listitem>
          <listitem>
            <para>
            Hibernate user documentation: <ulink 
              url="http://www.hibernate.org/hib_docs/reference/en/html/mapping.html#mapping-declaration-manytoone">5.1.10. many-to-one</ulink>
            </para>
          </listitem>
          </itemizedlist>
          
        </simplesect>
        
        <simplesect id="core_ref.rules.datalayer.manytomany">
          <title>Many-to-many and one-to-many mappings</title>
          
          <para>
            There are many variants of mapping many-to-many or one-to-many, and it is 
            not possible to give examples of all of them. In the code these mappings 
            are represented by <classname>Set</classname>:s, <classname>Map</classname>:s,
            <classname>List</classname>:s, or some other collection object. The most 
            important thing to remember is that (in our application) the collections 
            are only used to maintain the links between objects. They are not used 
            for returning objects to client applications, as is the case with the 
            many-to-one mapping.
          </para>
          
          <para>
            For example, if we want to find all members of a group we do not use the 
            <code>GroupData.getUsers()</code> method, instead we will execute a database query
            to retrieve them. The reason for this design is that the logged in user may 
            not have access to all users and we must add a permission checking filter 
            before returning the user objects to the client application. Using a query
            will also allow client applications to specify sorting and filtering options 
            for the users that are returned.
          </para>
          
          <programlisting language="java">
// RoleData.java
private Set&lt;UserData&gt; users;
/**
   Many-to-many from roles to users
   @hibernate.set table="`UserRoles`" lazy="true"
   @hibernate.collection-key column="`role_id`"
   @hibernate.collection-many-to-many column="`user_id`" 
      class="net.sf.basedb.core.data.UserData"
*/
public Set&lt;UserData&gt; getUsers()
{
   if (users == null) users = new HashSet&lt;UserData&gt;();
   return users;
}
void setUsers(Set&lt;UserData&gt; users)
{
   this.users = users;
}
</programlisting>
          
          <para>
            As you can see this mapping is a lot more complicated than what we have 
            seen before. The most important thing is the <code>lazy</code> attribute. 
            It tells Hibernate to delay the loading of the related objects until the set 
            is accessed. If the value is false or missing, Hibernate will load all objects 
            immediately. There is almost never a good reason to specify something other 
            than <code>lazy="true"</code>.
          </para>
          
          <para>
            Another important thing to remember is that the get method must always return 
            the same object that Hibernate passed to the set method. Otherwise, Hibernate 
            will not be able to detect changes made to the collection and as a result 
            will have to delete and then recreate all links. To ensure that the collection
            object is not changed we have made the <methodname>setUsers()</methodname> method 
            package private, and the <methodname>getUsers()</methodname> will create a 
            new <classname>HashSet</classname> for us only if Hibernate didn't pass one 
            in the first place.
          </para>
          
          <para>
            Let's also have a look at the reverse mapping:
          </para>
          
          <programlisting language="java">
// UserData.java
private Set&lt;RoleData&gt; roles;
/**
   Many-to-many from users to roles
   @hibernate.set table="`UserRoles`" lazy="true"
   @hibernate.collection-key column="`user_id`"
   @hibernate.collection-many-to-many column="`role_id`" 
      class="net.sf.basedb.core.data.RoleData"
*/
Set&lt;RoleData&gt; getRoles()
{
   return roles;
}
void setRoles(Set&lt;RoleData&gt; roles)
{
   this.roles = roles;
}
</programlisting>

          <para>
            The only real difference here is that both the setter and the getter methods 
            are package private. This is required because Hibernate will get confused if 
            we modify both ends. Thus, we are forced to always add/remove users to/from 
            the set in the <classname docapi="net.sf.basedb.core.data">GroupData</classname> object. The methods in the
            <classname docapi="net.sf.basedb.core.data">RoleData</classname> class are never used by us.
            Note that we do not have to check for null and create a new set since Hibernate 
            will handle null values as an empty set.
          </para>
          
          <para>
            So, why do we need the second collection at all? It is never accessed 
            except by Hibernate, and since it is lazy it will always be "empty". 
            The answer is that we want to use the relation in HQL statements.
            For example:
          </para>
          
          <programlisting language="sql">
SELECT ... FROM GroupData grp WHERE grp.users ...
SELECT ... FROM UserData usr WHERE usr.groups ...
</programlisting>
          
          <para>
            Without the inverse mapping, it would not have been possible to execute 
            the second HQL statement. The inverse mapping is also important in 
            parent-child relationships, where it is used to cascade delete the children 
            if a parent is deleted.
          </para>

          <warning>
            <title>Do not use the inverse="true" setting</title>
            <para>
              Hibernate defines an <code>inverse="true"</code> setting that can be used with 
              the <code>@hibernate.set</code> tag. If specified, Hibernate will ignore 
              changes made to that collection. However, there is one problem with specifying 
              this attribute. Hibernate doesn't delete entries in the association table, 
              leading to foreign key violations if we try to delete a user. The only 
              solutions are to skip the <code>inverse="true"</code> attribute or to 
              manually delete the object from all collections on the non-inverse end. 
              The first alternative is the most efficient since it only requires a 
              single SQL statement. The second alternative must first load all associated 
              objects and then issue a single delete statement for each association.
            </para>
            
            <para>
              In the "Hibernate in action" book they have a very different design 
              where they recommend that changes are made in both collections. We don't 
              have to do this since we are only interested in maintaining the links, 
              which is always done in one of the collections.
            </para>
          </warning>

          <bridgehead>Parent-child relationships</bridgehead>

          <para>
            When one or more objects are tightly linked to some other object we talk 
            about a parent-child relationship. This kind of relationship becomes important 
            when we are about to delete a parent object. The children cannot exist
            without the parent so they must also be deleted. Luckily, Hibernate can 
            do this for us if we specify a <code>cascade="delete"</code> option for the link. 
            This example is a one-to-many link between client and help texts.
          </para>

          <programlisting language="java">
// ClientData.java
private Set&lt;HelpData&gt; helpTexts;
/**
   This is the inverse end.
   @see HelpData#getClient()
   @hibernate.set lazy="true" inverse="true" cascade="delete"
   @hibernate.collection-key column="`client_id`"
   @hibernate.collection-one-to-many class="net.sf.basedb.core.data.HelpData"
*/
Set&lt;HelpData&gt; getHelpTexts()
{
   return helpTexts;
}

void setHelpTexts(Set&lt;HelpData&gt; helpTexts)
{
   this.helpTexts = helpTexts;
}

// HelpData.java
private ClientData client;
/**
   Get the client for this help text.
   @hibernate.many-to-one column="`client_id`" not-null="true" 
      update="false" outer-join="false" unique-key="uniquehelp"
*/
public ClientData getClient()
{
   return client;
}
public void setClient(ClientData client)
{
   this.client = client;
}
</programlisting>

          <para>
            This show both sides of the one-to-many mapping between parent and children. 
            As you can see the <code>@hibernate.set</code> doesn't specify a table, 
            since it is given by the <code>class</code> attribute of the 
            <code>@hibernate.collection-one-to-many</code> tag. 
          </para>
          
          <para>
            In a one-to-many mapping, it is always the "one" side that handles the 
            link so the "many" side should always be mapped with <code>inverse="true"</code>.
          </para>

          <bridgehead>Maps</bridgehead>
          
          <para>
            Another type of many-to-many mapping uses a <interfacename>Map</interfacename>
            for the collection. This kind of mapping is needed when the association between
            two objects needs additional data to be kept as part of the association.
            For example, the permission (stored as an integer value) given to users that 
            are members of a project. Note that you should use a <interfacename>Set</interfacename>
            for mapping the inverse end.
          </para>
          
          <programlisting language="java">
// ProjectData.java
private Map&lt;UserData, Integer&gt; users;
/**
   Many-to-many mapping between projects and users including permission values.
   @hibernate.map table="`UserProjects`" lazy="true"
   @hibernate.collection-key column="`project_id`"
   @hibernate.index-many-to-many column="`user_id`" 
      class="net.sf.basedb.core.data.UserData"
   @hibernate.collection-element column="`permission`" type="int" not-null="true"
*/
public Map&lt;UserData, Integer&gt; getUsers()
{
   if (users == null) users = new HashMap&lt;UserData, Integer&gt;();
   return users;
}
void setUsers(Map&lt;UserData, Integer&gt; users)
{
   this.users = users;
}

// UserData.java
private Set&lt;ProjectData&gt; projects;
/**
   This is the inverse end.
   @see ProjectData#getUsers()
   @hibernate.set table="`UserProjects`" lazy="true"
   @hibernate.collection-key column="`user_id`"
   @hibernate.collection-many-to-many column="`project_id`"
      class="net.sf.basedb.core.data.ProjectData"
*/
Set&lt;ProjectData&gt; getProjects()
{
   return projects;
}
void setProjects(Set&lt;ProjectData&gt; projects)
{
   this.projects = projects;
}
</programlisting>
        
        <para>
          See also:
        </para>
        
        <itemizedlist>
          <listitem>
            <para>
            "Hibernate in action", chapter 3.7 "Introducing associations", page 105-112
            </para>
          </listitem>
          <listitem>
            <para>
            "Hibernate in action", chapter 6.2 "Mapping collections of value types", page 211-220
            </para>
          </listitem>
          <listitem>
            <para>
            "Hibernate in action", chapter 6.3.2 "Many-to-many associations", page 225-233
            </para>
          </listitem>
          <listitem>
            <para>
            Hibernate user documentation: <ulink 
              url="http://www.hibernate.org/hib_docs/reference/en/html/collections.html">Chapter 6. Collection Mapping</ulink>
            </para>
          </listitem>
          <listitem>
            <para>
            Hibernate user documentation: <ulink 
              url="http://www.hibernate.org/hib_docs/reference/en/html/example-parentchild.html">Chapter 21. Example: Parent/Child</ulink>
            </para>
          </listitem>
          </itemizedlist>
        

        </simplesect>
        
        <simplesect id="core_ref.rules.datalayer.onetoone">
          <title>One-to-one mappings</title>
          
          <para>
            A one-to-one mapping can come in two different forms, depending on if both
            objects should have the same id or not. We start with the case were the objects 
            can have different id:s and the link is done with an extra column in one of 
            the tables. The example is from the mapping between hybridizations and 
            arrayslides.
          </para>
          
          <programlisting language="java">
// HybridizationData.java
private ArraySlideData arrayslide;
/**
   Get the array slide
   @hibernate.many-to-one column="`arrayslide_id`" not-null="false" unique="true"
*/
public ArraySlideData getArraySlide()
{
   return arrayslide;
}
public void setArraySlide(ArraySlideData arrayslide)
{
   arrayslide.setHybridization(this);
   this.arrayslide = arrayslide;
}

// ArraySlideData.java
private HybridizationData hybridization;
/**
   Get the hybridization
   @hibernate.one-to-one property-ref="arraySlide"
*/
public HybridizationData getHybridization()
{
   return hybridization;
}
void setHybridization(HybridizationData hybridization)
{
   this.hybridization = hybridization;
}         
</programlisting>
          
          <para>
            As you can see, we use the many-to-one mapping on with a <code>unique="true"</code>
            option for the hybridization. This will force the database to only allow the 
            same array slide to be linked once. Also note that since, <code>not-null="false"</code>,
            null values are allowed and it doesn't matter which end of the relation that
            is inserted first into the database.
          </para>
          <para>
            For the array slide end we use a <code>@hibernate.one-to-one</code>
            mapping and specify the name of the property on the other end that we are
            linking to. Also, note that the we can only change the link with the 
            <methodname>HybridizationData.setArraySlide()</methodname> method, and that 
            this method also updates the other end.
          </para>

          <para>
            The second form of a one-to-one mapping is used when both objects must 
            have the same id (primary key). The example is from the mapping between users 
            and passwords.
          </para>
          
          <programlisting language="java">
// UserData.java
/**
   @hibernate.id column="`id`" generator-class="foreign"
   @hibernate.generator-param name="property" value="password"
*/
public int getId()
{
   return super.getId();
}
private PasswordData password;
/**
   Get the password.
   @hibernate.one-to-one class="net.sf.basedb.core.data.PasswordData"
      cascade="all" outer-join="false" constrained="true"
*/
public PasswordData getPassword()
{
   if (password == null)
   {
      password = new PasswordData();
      password.setUser(this);
   }
   return password;
}
void setPassword(PasswordData user)
{
   this.password = password;
}

// PasswordData.java
private UserData user;
/**
   Get the user.
   @hibernate.one-to-one class="net.sf.basedb.core.data.UserData"
*/
public UserData getUser()
{
   return user;
}
void setUser(UserData user)
{
   this.user = user;
}
</programlisting>
          
          <para>
            In this case, we use the <code>@hibernate.one-to-one</code> mapping
            in both classes. The <code>constrained="true"</code> tag in <classname docapi="net.sf.basedb.core.data">UserData</classname>
            tells Hibernate to always insert the password first, and then the user. The makes it
            possible to use the (auto-generated) id for the password as the id 
            for the user. This is controlled by the mapping for the <methodname>UserData.getId()</methodname>
            method, which uses the <code>foreign</code> id generator. This generator will look 
            at the password property, ie. call <methodname>getPassword().getId()</methodname>
            to find the id for the user. Also note the initialisation code and <code>cascade="all"</code>
            tag in the <methodname>UserData.getPassword()</methodname> method. This is need
            to avoid <classname>NullPointerException</classname>:s and to make sure everything
            is created and deleted properly.
          </para>
          
          <para>
            See also:
          </para>
          
        <itemizedlist>
          <listitem>
            <para>
            "Hibernate in action", chapter 6.3.1 "One-to-one association", page 220-225
            </para>
          </listitem>
          <listitem>
            <para>
            Hibernate user documentation: <ulink 
              url="http://www.hibernate.org/hib_docs/reference/en/html/mapping.html#mapping-declaration-onetoone">5.1.11. one-to-one</ulink>
            </para>
          </listitem>
          </itemizedlist>
          
        </simplesect>
        
      </sect3>

      <sect3 id="core_ref.rules.datalayer.documentation">
        <title>Documentation</title>

        <para>
          The data layer code needs documentation. A simple approach is used for
          Javadoc documentation
        </para>
        
        <simplesect id="core_ref.rules.datalayer.documentation.class">
          <title>Class documentation</title>
          <para>
            The documentation for the class doesn't have to be very lengthy. A single 
            sentence is usually enough. Provide tags for the author, version, last modification date 
            and a reference to the corresponding class in the <package>net.sf.basedb.core</package>
            package.
          </para>
          
          <programlisting language="java">
/**
   This class holds information about any items.

   @author Your name
   @version 2.0
   @see net.sf.basedb.core.AnyItem
   @base.modified $Date: 2007-08-17 09:18:29 +0200 (Fri, 17 Aug 2007) $
   @hibernate.class table="`Anys`" lazy="false"
*/
public class AnyData
   extends CommonData
{
...
}
</programlisting>
          
        </simplesect>
        
        <simplesect id="core_ref.rules.datalayer.documentation.method">
          <title>Method documentation</title>
          
          <para>
          Write a short one-sentence description for all public getter methods. You do not 
          have document the parameters or the setter methods, since it would just be a 
          repetition. Methods defined by interfaces are documented in the interface class. 
          You should not have to write any documentation for those methods.
          </para>
          
          <para>
            For the inverse end of an association, which has only package private methods, 
            write a notice about this and provide a link to to non-inverse end.
          </para>
          
          <programlisting language="java">
// UserData.java
private String address;
/**
   Get the address for the user.
   @hibernate.property column="`address`" type="string" length="255"
*/
public String getAddress()
{
   return address;
}
public void setAddress(String address)
{
   this.address = address;
}

private Set&lt;GroupData&gt; groups;
/**
   This is the inverse end.
   @see GroupData#getUsers()
   @hibernate.set table="`UserGroups`" lazy="true" inverse="true"
   @hibernate.collection-key column="`user_id`"
   @hibernate.collection-many-to-many column="`group_id`"
      class="net.sf.basedb.core.data.GroupData"
*/
Set&lt;GroupData&gt; getGroups()
{
   return groups;
}
void setGroups(Set&lt;GroupData&gt; groups)
{
   this.groups = groups;
}
</programlisting>
          
        </simplesect>
        
        <simplesect id="core_ref.rules.datalayer.documentation.field">
          <title>Field documentation</title>
          <para>
            Write a short one-sentence description for <code>public static final</code>
            fields. Private fields does not have to be documented.
          </para>
          
          <programlisting language="java">
/**
   The maximum length of the name of an item that can be
   stored in the database.
   @see #setName(String)
*/
public static int MAX_NAME_LENGTH = 255;
</programlisting>

        </simplesect>
        
        <simplesect id="core_ref.rules.datalayer.documentation.uml">
          <title>UML diagram</title>
          
          <para>
            Groups of related classes should be included in an UML-like 
            diagram to show how they are connected and work together.
            For example we group together users, groups, roles, etc. into an 
            authentication UML diagram. It is also possible that a single class 
            may appear in more than one diagram. For more information about
            how to create UML diagrams see 
            <xref linkend="documentation.magicdraw" />.
          </para>
        </simplesect>

        
      </sect3>

    </sect2>
    <sect2 id="core_ref.rules.itemclass">
      <title>Item-class rules</title>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/development/coding/item/index.html"
          >http://base.thep.lu.se/chrome/site/doc/historical/development/coding/item/index.html</ulink>
      </para>
    </sect2>    
    <sect2 id="core_ref.rules.batchclass">
      <title>Batch-class rules</title>
      <para>
        TODO
      </para>
    </sect2>    
    <sect2 id="core_ref.rules.testclass">
      <title>Test-class rules</title>
      <para>
        TODO
      </para>
    </sect2>    
  </sect1>
  
  <sect1 id="core_ref.coreinternals">
    <title>Internals of the Core API</title>
    <para>
      This documentation is only available in the old format.
      See <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/index.html"
        >http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/index.html</ulink>
    </para>
    <sect2 id="core_ref.authentication">
      <title>Authentication and sessions</title>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/authentication.html"
          >http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/authentication.html</ulink>
      </para>
    </sect2>    
    <sect2 id="core_ref.accesspermissions">
      <title>Access permissions</title>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/accesspermissions.html"
          >http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/accesspermissions.html</ulink>
      </para>
    </sect2>    
    <sect2 id="core_ref.datavalidation">
      <title>Data validation</title>
      <para>
        TODO
      </para>
    </sect2>    
    <sect2 id="core_ref.transactions">
      <title>Transaction handling</title>
      <para>
        TODO
      </para>
    </sect2>    
    <sect2 id="core_ref.crwd">
      <title>Create/read/write/delete operations</title>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/itemhandling.html"
          >http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/itemhandling.html</ulink>
      </para>
    </sect2>    
    <sect2 id="core_ref.batch">
      <title>Batch operations</title>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/batchprocessing.html"
          >http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/batchprocessing.html</ulink>
      </para>
    </sect2>    
    <sect2 id="core_ref.quota">
      <title>Quota</title>
      <para>
        TODO
      </para>
    </sect2>    
    <sect2 id="core_ref.pluginexecution">
      <title>Plugin execution / job queue</title>
      <para>
        This documentation is only available in the old format.
        See <ulink url="http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/plugins.html"
          >http://base.thep.lu.se/chrome/site/doc/historical/development/overview/core/plugins.html</ulink>
      </para>
    </sect2>    
  </sect1>

</chapter>