Changeset 3916

Timestamp:

Nov 6, 2007, 1:03:23 PM (16 years ago)

Author:

Nicklas Nordborg

Message:

References #746: Transfer existing UML diagrams to latest MagicDraw?

• Finished parameters section
• Added biomaterials sections

Location:

trunk/doc/src

Files:

• docbook/developerdoc/api_overview.xml (modified) (2 diffs)
• docbook/figures/uml/datalayer.biomaterials.png (added)
• uml/baseuml.mdzip (modified) (previous)

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

@@ -1233 +1233 @@
       </sect3>
       
+      <sect3 id="data_api.parameters.description">
+        <title>Parameters</title>
+        
+        <para>
+          The parameter system is a generic system that can store almost
+          any kind of simple values (string, numbers, dates, etc.) and
+          also links to other items. The <classname>ParameterValueData</classname> 
+          class is an abstract base class that can hold multiple values (all must be of the
+          same type). Unless only a specific type of values should be stored, this is 
+          the class that should be used when creating references for storing parameter
+          values. It makes it possible for a single relaltion to use any kind of
+          values or for a collection reference to mix multiple types of values.
+          A typical use case maps a <classname>Map</classname> with the 
+          parameter name as the key:
+        </para>
+        
+        <programlisting language="java">
+private Map&lt;String, ParameterValueData&lt;?&gt;&gt; configurationValues;
+/**
+   Link parameter name with it's values.
+   @hibernate.map table="`PluginConfigurationValues`" lazy="true" cascade="all"
+   @hibernate.collection-key column="`pluginconfiguration_id`"
+   @hibernate.collection-index column="`name`" type="string" length="255"
+   @hibernate.collection-many-to-many column="`value_id`" 
+      class="net.sf.basedb.core.data.ParameterValueData"
+*/
+public Map&lt;String, ParameterValueData&lt;?&gt;&gt; getConfigurationValues()
+{
+   return configurationValues;
+}
+void setConfigurationValues(Map&lt;String, ParameterValueData&lt;?&gt;&gt; configurationValues)
+{
+   this.configurationValues = configurationValues;
+}
+</programlisting>
+        
       <para>
-      TODO
+      Now it is possible for the collection to store all types of values:
       </para>
+      
+      <programlisting language="java">
+Map&lt;String, ParameterValueData&lt;?&gt;&gt; config = ...
+config.put("names", new StringParameterValueData("A", "B", "C"));
+config.put("sizes", new IntegerParameterValueData(10, 20, 30));
+
+// When you later load those values again you have to cast 
+// them to the correct class.
+List&lt;String&gt; names = (List&lt;String&gt;)config.get("names").getValues();
+List&lt;Integer&gt; sizes = (List&lt;Integer&gt;)config.get("sizes").getValues();
+</programlisting>
+
+      </sect3>
       
     </sect2>
@@ -1623 +1672 @@
     <sect2 id="data_api.biomaterials">
       <title>Biomaterials</title>
+      
+      <sect3 id="data_api.biomaterials.uml">
+        <title>UML diagram</title>
+        
+        <figure id="data_api.figures.biomaterials">
+          <title>Biomaterials</title>
+          <screenshot>
+            <mediaobject>
+              <imageobject>
+                <imagedata 
+                  fileref="figures/uml/datalayer.biomaterials.png" format="PNG" />
+              </imageobject>
+            </mediaobject>
+          </screenshot>
+        </figure>
+      </sect3>
+      
+      <sect3 id="data_api.biomaterials.description">
+        <title>Biomaterials</title>
+        
+        <para>
+          There are four types of biomaterials: <classname>BioSourceData</classname>, 
+          <classname>SampleData</classname>, <classname>ExtractData</classname> and 
+          <classname>LabeledExtractData</classname>.
+          All four types of are derived from the base class <classname>BioMaterialData</classname>. 
+          The reason for this is that they all share common functionality such as pooling 
+          and events. By using a common base class we do not have to create duplicate 
+          classes for keeping track of events and parents.
+        </para>
+        
+        <para>
+          The <classname>BioSourceData</classname> is the simplest of the biomaterials. 
+          It cannot have parents and can't participate in events. It's only used as a 
+          (non-required) parent for samples.
+        </para>
+        
+        <para>
+          The <classname>MeasuredBioMaterialData</classname> class is used as a base 
+          class for the other three biomaterial types. It introduces quantity 
+          measurements and can store original and remaining quantities. They are 
+          both optional. If an original quantity has been specified the core 
+          automatically calculates the remaining quantity based on the events a 
+          biomaterial participates in.
+        </para>
+        
+        <para>
+          All measured biomaterial have at least one event associated with them, 
+          the creation event, which holds information about the creation of the 
+          biomaterial. A measured biomaterial can be created in three ways:
+        </para>
+        
+        <itemizedlist>
+        <listitem>
+          <para>
+          From a single item of the parent type. Biosource is the parent type of 
+          samples, sample is the parent type of extracts, and extract is the
+          parent type of labeled extracts. In this case the 
+          <property>pooled</property> property is <constant>false</constant>
+          and the parent is specified in the <property>parent</property> property. 
+          If the parent is not a <classname>BioSourceData</classname> this information 
+          is duplicated, with the addition of an optional used quantity value, in the 
+          <property>sources</property> collection of the <classname>BioMaterialEventData</classname>
+          object representing the creation event. It is the responsibility of the 
+          core to make sure that everything is properly synchronized and that 
+          remaining quantities are calculated.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+          From one or more items of the same type, i.e pooling.
+          In this case the <property>pooled</property> property is <constant>true</constant> 
+          and the <property>parent</property> property is null. All source 
+          biomaterials are contained in the <property>sources</property> collection. 
+          The core is still responsible for keeping everything synchronized and to
+          update remaining quantities.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+          As a standalone biomaterial without parents.
+          </para>
+        </listitem>
+        </itemizedlist>
+
+      </sect3>
+      
+      <sect3 id="data_api.biomaterials.events">
+        <title>Biomaterial events</title>
+        
+        <para>
+          An event represents something that happened to one or more biomaterials, for example 
+          the creation of another biomaterial. The <classname>BioMaterialEventData</classname>
+          holds information about entry and event dates, protocols used, the user who is 
+          responsible, etc. There are three types of events represented by the <property>eventType</property>
+          property.
+        </para>
+        
+        <orderedlist>
+        <listitem>
+          <para>
+          <emphasis>Creation event</emphasis>: This event represents the creation of a (measured) 
+          biomaterial. The <property>sources</property> collection contains 
+          information about the biomaterials that were used to create the new 
+          biomaterial. If the biomaterial is a pooled biomaterial all sources must 
+          be of the same type. Otherwise there can only be one source of the parent 
+          type. These rules are maintained by the core.
+          </para>
+        </listitem>
+        
+        <listitem>
+          <para>
+          <emphasis>Hybridization event</emphasis>: This event represents the creation 
+          of a hybridization. This event type is needed because we want to keep track
+          of quantities for labeled extracts. This event has a hybridization as a 
+          product instead of a biomaterial. The sources collection can only contain 
+          labeled extracts.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+          <emphasis>Other event</emphasis>: This event represents some other important
+          information about a single biomaterial that affected the remaining quantity. 
+          This event type doesn't have any sources.
+          </para>
+        </listitem>
+        </orderedlist>
+      </sect3>
+  
     </sect2>