Changeset 5071


Ignore:
Timestamp:
Aug 21, 2009, 8:17:57 AM (13 years ago)
Author:
Nicklas Nordborg
Message:

References #108: Logging the change history of an item

  • Added the new data classes to UML diagram and made updates to all other affected diagrams
  • Documented the logging feature for plug-in developers
  • Made the new data classes immutable
Location:
trunk
Files:
18 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/appendix/base.config.xml

    r5023 r5071  
    564564  </simplesect>
    565565 
     566  <simplesect id="appendix.base.config.log">
     567    <title>Change history logging section</title>
     568   
     569    <para>
     570      This section contains settings for logging the change history
     571      of items.
     572    </para>
     573   
     574    <variablelist>
     575    <varlistentry>
     576      <term><property>changelog.factory</property></term>
     577      <listitem>
     578        <para>
     579        The factory class that controls the entire logging system. The
     580        factory has control of what should be logged, were it should
     581        be logged, etc. BASE ships with one factory implementation
     582        <classname docapi="net.sf.basedb.core.log.db">DbLogManagerFactory</classname>
     583        which logs changes into tables in the database. The server admin
     584        may choose a different implementation provided that it implements
     585        the <interfacename docapi="net.sf.basedb.core.log">LogManagerFactory</interfacename>
     586        interface. See <xref linkend="plugin_developer.other.logging" />.
     587        If no factory is specified, logging is disabled.
     588          </para>
     589      </listitem>
     590    </varlistentry>
     591    <varlistentry>
     592      <term><property>changelog.show-in-web</property></term>
     593      <listitem>
     594        <para>
     595        A boolean value that specifies if the <guilabel>Change history</guilabel>
     596        tab should be visible in the web interface or not. The change history
     597        tab will show log information that has been stored in the database
     598        and it doesn't make sense to show this tab unless the
     599        <classname docapi="net.sf.basedb.core.log.db">DbLogManagerFactory</classname>
     600        is used.
     601          </para>
     602         
     603          <note>
     604            <para>
     605            By default, only users that are members of the
     606            <guilabel>Administrator</guilabel> role have permission to
     607            view the change history. To give other users the same permission,
     608            add the <guilabel>Change history</guilabel> permission to
     609            the appropriate role(s).
     610            </para>
     611          </note>
     612      </listitem>
     613    </varlistentry>
     614    <varlistentry>
     615      <term><property>changelog.dblogger.detailed-properties</property></term>
     616      <listitem>
     617        <para>
     618        A boolean value that specifies the amount of information
     619        that should be logged. If set, the log will contain information
     620        about which properties that was modified on each item,
     621        otherwise only the type of change (create, update, delete) is
     622        logged.
     623        </para>
     624      </listitem>
     625    </varlistentry>
     626    </variablelist>
     627   
     628  </simplesect>
     629 
    566630  <simplesect id="appendix.base.config.secondary.other">
    567631    <title>Other settings</title>
  • trunk/doc/src/docbook/developerdoc/api_overview.xml

    r4902 r5071  
    405405            This interface is used by items which registered the date they were
    406406            created in the database. The registration date is set at creation time
    407             and can't be modified later. Since this didn't exist prior to BASE 2.10
     407            and can't be modified later. Since this didn't exist prior to BASE 2.10,
    408408            null values are allowed on all pre-existing items. Note! For backwards
    409409            compatibility reasons with existing code in
    410410            <classname docapi="net.sf.basedb.core.data">BioMaterialEventData</classname>
    411411            the method name is <methodname>getEntryDate()</methodname>.
     412            </para>
     413          </listitem>
     414        </varlistentry>
     415       
     416        <varlistentry>
     417          <term><interfacename docapi="net.sf.basedb.core.data">LoggableData</interfacename></term>
     418          <listitem>
     419            <para>
     420            This is a tagging interface that indicates that the <classname
     421            docapi="net.sf.basedb.core.log.db">DbLogManagerFactory</classname> logging
     422            implementation should log changes made to items that implements it.
    412423            </para>
    413424          </listitem>
  • trunk/doc/src/docbook/developerdoc/documentation.xml

    r4889 r5071  
    15001500                <listitem><para>F = FileAttachableData</para></listitem>
    15011501                <listitem><para>G = RegisteredData</para></listitem>
     1502                <listitem><para>L = LoggableData</para></listitem>
    15021503                <listitem><para>N = NameableData</para></listitem>
    15031504                <listitem><para>O = OwnableData</para></listitem>
  • trunk/doc/src/docbook/developerdoc/plugin_developer.xml

    r5013 r5071  
    44294429    </sect2>
    44304430   
     4431    <sect2 id="plugin_developer.other.logging">
     4432      <title>Logging plug-ins</title>
     4433     
     4434      <para>
     4435        BASE provides a plug-in mechanism for logging changes that are made to items.
     4436        This plug-in mechanism is not the same as the regular plug-in API. That is, you do not
     4437        have worry about user interaction or implementing the <interfacename
     4438        docapi="net.sf.basedb.core.plugin">Plugin</interfacename> interface.
     4439      </para>
     4440     
     4441      <para>
     4442        The logging mechanism works on the data layer level and hooks into
     4443        callbacks provided by Hibernate. <interfacename
     4444        docapi="net.sf.basedb.core.log">EntityLogger</interfacename>:s are used to
     4445        extract relevant information from Hibernate and create log entries.
     4446        While it is possible to have a generic logger it is usually better
     4447        to have different implementations depending on the type of entity that
     4448        was changed. For example, a change in a child item should, for usability
     4449        reasons, be logged as a change in the parent item. Entity loggers
     4450        are created by a <interfacename
     4451        docapi="net.sf.basedb.core.log">LogManagerFactory</interfacename>. All changes
     4452        made in a single transaction are usually collected by a <interfacename
     4453        docapi="net.sf.basedb.core.log">LogManager</interfacename> which is also
     4454        created by the factory.
     4455      </para>
     4456     
     4457      <sect3 id="plugin_developer.other.logmanagerfactory">
     4458        <title>The LogManagerFactory interface</title>
     4459       
     4460        <para>
     4461          Which <interfacename
     4462          docapi="net.sf.basedb.core.log">LogManagerFactory</interfacename> to use
     4463          is configured in <filename>base.config</filename> (See <xref
     4464          linkend="appendix.base.config.log"/>). A single factory instance is created
     4465          when BASE starts and is used for the lifetime of the virtual machine. The
     4466          factory implementation must of course be thread-safe. Here is a list of
     4467          the methods the factory must implement:
     4468        </para>
     4469       
     4470        <variablelist>
     4471          <varlistentry>
     4472            <term>
     4473              <methodsynopsis language="java">
     4474                <modifier>public</modifier>
     4475                <type>LogManager</type>
     4476                <methodname>getLogManager</methodname>
     4477                <methodparam>
     4478                  <type>LogControl</type>
     4479                  <parameter>logControl</parameter>
     4480                </methodparam>
     4481              </methodsynopsis>
     4482            </term>
     4483            <listitem>
     4484              <para>
     4485              Creates a log manager for a single transaction. Since a transaction
     4486              is not thread-safe the log manager implementation doesn't have to
     4487              be either. The factory has the possibility to create new log managers
     4488              for each transaction.
     4489              </para>
     4490            </listitem>
     4491          </varlistentry>
     4492         
     4493          <varlistentry>
     4494            <term>
     4495              <methodsynopsis language="java">
     4496                <modifier>public</modifier>
     4497                <type>boolean</type>
     4498                <methodname>isLoggable</methodname>
     4499                <methodparam>
     4500                  <type>Object</type>
     4501                  <parameter>entity</parameter>
     4502                </methodparam>
     4503              </methodsynopsis>
     4504            </term>
     4505            <listitem>
     4506              <para>
     4507              Checks if changes to the given entity should be
     4508              logged or not. For performance reasons, it usually makes sense to
     4509              not log everything. For example, the database logger implementation
     4510              only logs changes if the entity implements the <interfacename
     4511              docapi="net.sf.basedb.core.data">LoggableData</interfacename>
     4512              interface. The return value of this method should be consistent
     4513              with <methodname>getEntityLogger()</methodname>.
     4514              </para>
     4515            </listitem>
     4516          </varlistentry>
     4517
     4518          <varlistentry>
     4519            <term>
     4520              <methodsynopsis language="java">
     4521                <modifier>public</modifier>
     4522                <type>EntityLogger</type>
     4523                <methodname>getEntityLogger</methodname>
     4524                <methodparam>
     4525                  <type>LogManager</type>
     4526                  <parameter>logManager</parameter>
     4527                </methodparam>
     4528                <methodparam>
     4529                  <type>Object</type>
     4530                  <parameter>entity</parameter>
     4531                </methodparam>
     4532              </methodsynopsis>
     4533            </term>
     4534            <listitem>
     4535              <para>
     4536              Create or get an entity logger that knows how to log
     4537              changes to the given entity. If the entity should not be
     4538              logged, <constant>null</constant> can be returned. This method
     4539              is called for each modified item in the transaction.
     4540              </para>
     4541            </listitem>
     4542          </varlistentry>
     4543        </variablelist>
     4544       
     4545      </sect3>
     4546     
     4547      <sect3 id="plugin_developer.other.logmanager">
     4548        <title>The LogManager interface</title>
     4549       
     4550        <para>
     4551          A new log manager is created for each transaction. The log manager
     4552          is responsible for collecting all changes made in the transaction
     4553          and store those changes in the appropriate place. The interface doesn't define
     4554          any methods for this collection, since each implementation may have
     4555          very different needs.
     4556        </para>
     4557       
     4558        <variablelist>
     4559          <varlistentry>
     4560            <term>
     4561              <methodsynopsis language="java">
     4562                <modifier>public</modifier>
     4563                <type>LogControl</type>
     4564                <methodname>getLogControl</methodname>
     4565              </methodsynopsis>
     4566            </term>
     4567            <listitem>
     4568              <para>
     4569              Get the log control object that was supplied by the BASE core
     4570              when the transaction was started. The log controller contains
     4571              methods for accessing information about the transaction, such
     4572              as the logged in user, executing plug-in, etc. It can also
     4573              be used to execute queries against the database to get
     4574              even more information.
     4575              </para>
     4576             
     4577              <warning>
     4578                <para>
     4579                  Be careful about the queries that are executed by the log
     4580                  controller. Since all logging code is executed at flush
     4581                  time in callbacks from Hibernate we are not allowed to
     4582                  use the regular session. Instead, all queries are sent
     4583                  through the stateless session. The stateless session has no
     4584                  caching functionality which means that Hibernate will use
     4585                  extra queries to load associations. Our recommendation is
     4586                  to avoid quires that return full entities, use scalar
     4587                  queries instead to just load the values that are needed.
     4588                </para>
     4589              </warning>
     4590            </listitem>
     4591          </varlistentry>
     4592          <varlistentry>
     4593            <term>
     4594              <methodsynopsis language="java">
     4595                <modifier>public</modifier>
     4596                <void/>
     4597                <methodname>afterCommit</methodname>
     4598              </methodsynopsis>
     4599            </term>
     4600            <term>
     4601              <methodsynopsis language="java">
     4602                <modifier>public</modifier>
     4603                <void/>
     4604                <methodname>afterRollback</methodname>
     4605              </methodsynopsis>
     4606            </term>
     4607            <listitem>
     4608              Called after a successful commit or after a rollback. Note
     4609              that the connection to the database has been closed at this
     4610              time and it is not possible to save any more information to
     4611              it at this time.
     4612            </listitem>
     4613          </varlistentry>
     4614        </variablelist>
     4615      </sect3>
     4616
     4617      <sect3 id="plugin_developer.other.entitylogger">
     4618        <title>The EntityLogger interface</title>
     4619       
     4620        <para>
     4621          An entity logger is responsible for extracting the changes
     4622          made to an entity and converting it to something that is useful
     4623          as a log entry. In most cases, this is not very complicated, but
     4624          in some cases, a change in one entity should actually be logged
     4625          as a change in a different entity. For example, changes to
     4626          annotations are handled by the <classname
     4627          docapi="net.sf.basedb.core.log.db">AnnotationLogger</classname> which
     4628          which log it as a change on the parent item.
     4629        </para>
     4630       
     4631        <variablelist>
     4632          <varlistentry>
     4633            <term>
     4634              <methodsynopsis language="java">
     4635                <modifier>public</modifier>
     4636                <void/>
     4637                <methodname>logChanges</methodname>
     4638                <methodparam>
     4639                  <type>LogManager</type>
     4640                  <parameter>logManager</parameter>
     4641                </methodparam>
     4642                <methodparam>
     4643                  <type>EntityDetails</type>
     4644                  <parameter>details</parameter>
     4645                </methodparam>
     4646              </methodsynopsis>
     4647            </term>
     4648            <listitem>
     4649              <para>
     4650              This method is called whenever a change has been detected
     4651              in an entity. The <varname>details</varname> variable contains
     4652              information about the entity and, to a certain degree,
     4653              what changes that has been made.
     4654              </para>
     4655            </listitem>
     4656          </varlistentry>
     4657        </variablelist>
     4658      </sect3>
     4659    </sect2>
    44314660  </sect1>
    44324661 
  • trunk/src/core/net/sf/basedb/core/data/ChangeHistoryData.java

    r5048 r5071  
    5050  @version 2.13
    5151  @base.modified $Date$
    52   @hibernate.class table="`ChangeHistory`" lazy="false"
     52  @hibernate.class table="`ChangeHistory`" lazy="false" mutable="false"
    5353*/
    5454public class ChangeHistoryData
  • trunk/src/core/net/sf/basedb/core/data/ChangeHistoryDetailData.java

    r5038 r5071  
    3131  @version 2.13
    3232  @base.modified $Date$
    33   @hibernate.class table="`ChangeHistoryDetails`" lazy="false"
     33  @hibernate.class table="`ChangeHistoryDetails`" lazy="false" mutable="false"
    3434*/
    3535public class ChangeHistoryDetailData
Note: See TracChangeset for help on using the changeset viewer.