source: trunk/doc/src/docbook/developer/extensions.xml @ 7548

<?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: extensions.xml 7548 2018-12-10 11:53:32Z nicklas $
  
  Copyright (C) 2008
  
  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="extensions_developer">
  <?dbhtml dir="extensions" filename="index.html" ?>
  <title>Extensions developer</title>

  <sect1 id="extensions_developer.overview">
    <?dbhtml filename="overview.html" ?>
    <title>Overview</title>
    <para>
      The BASE application includes an extensions mechanism that makes it possible 
      to dynamically add functions to the GUI without having to edit the JSP code. 
      It is, for example, possible to add menu items in the menu and toolbar buttons 
      in selected toolbars. 
    </para>
    
    <para>
      Go to the 
        <menuchoice>
          <guimenu>Administrate</guimenu>
          <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
          <guimenuitem>Overview</guimenuitem>
        </menuchoice>
      menu to display a list of possible extension points and all installed 
      extensions. From this page, if you are logged in with enough permissions, 
      it is also possible to configure the extensions system, enable/disable
      extensions, etc. Read more about this in <xref linkend="plugins" />.
    </para>

    <para>
      Extensions can come in two forms, either as an XML file in the
      <emphasis>BASE Extensions XML</emphasis> format or as a JAR file. 
      A JAR file is required when the extension needs to execute custom-made
      code or use custom resources such as icons, css stylesheets, or 
      JSP files.
    </para>

    <itemizedlist>
      <title>More reading</title>
      <listitem>
        <para>
        <xref linkend="plugins" />.
        </para>
      </listitem>
      
      <listitem>
        <para>
        <xref linkend="core_api.extensions" />.
        </para>
      </listitem>
    </itemizedlist>

    <sect2 id="extensions_developer.examplecode">
      <title>Download code examples</title>

      <para>
        The code examples in this chapter can be downloaded from the
        BASE plug-ins site: 
        <ulink url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.examplecode"
        >http://baseplugins.thep.lu.se/wiki/net.sf.basedb.examplecode</ulink>
      </para>
    </sect2>

    <sect2 id="extensions_developer.terminology">
      <title>Terminology</title>
      
      <variablelist>
      <varlistentry>
        <term>Extension point</term>
        <listitem>
          <para>
          An extensions point is a place in the BASE core or web client interface
          where it is possible to extend the functionality with custom extensions. An 
          extension point has an ID which must be unique among all existing
          extension points. Extension points registered by the BASE web client all 
          starts with <code>net.sf.basedb.clients.web</code> prefix. The
          extension point also defines an 
          <interfacename docapi="net.sf.basedb.util.extensions">Action</interfacename>
          subclass that all extensions must implement.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Extension</term>
        <listitem>
          <para>
          An extensions is a custom addition to the BASE web client 
          interface or core API. This can mean a new menu item in the menu or a
          new button in a toolbar. An extension must provide an
          <interfacename docapi="net.sf.basedb.util.extensions">ActionFactory</interfacename>
          that knows how to create actions that fits the requirements
          from the extension point the extension is extending.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Action</term>
        <listitem>
          <para>
          An <interfacename docapi="net.sf.basedb.util.extensions">Action</interfacename>
          is an interface definition which provides an extension point enough 
          information to make it possible to render the action as HTML.
          An action typically has methods such as, <code>getTitle()</code>,
          <code>getIcon()</code> and <code>getOnClick()</code>. 
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Action factory</term>
        <listitem>
          <para>
          An <interfacename docapi="net.sf.basedb.util.extensions">ActionFactory</interfacename>
          is an object that knows how to create actions of some specific type, for
          example menu item actions. Action factories are part of an
          extension definition and can usually be configured with parameters
          from the XML file. BASE ships with several implementations of
          action factories for all defined extension points. Still, if your
          extension needs a different implementation you can easily create your
          own factory.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Renderer</term>
        <listitem>
          <para>
          A <interfacename docapi="net.sf.basedb.util.extensions">Renderer</interfacename>
          is an object that knows how to convert the information in an action to
          HTML. The use of renderers are optional. Some extension points use a
          "hard-coded" approach that renders the actions directly on the JSP file.
          Some extension points uses a locked renderer, while other extension
          points provides a default renderer, but allows extensions to supply their
          own if they want to. Renderers are mostly used by the web client extensions,
          not so much by the core extensions.
          </para>
        </listitem>
      </varlistentry>
  
      <varlistentry>
        <term>Renderer factory</term>
        <listitem>
          <para>
          A <interfacename docapi="net.sf.basedb.util.extensions">RendererFactory</interfacename>
          is an object that knows how to create renderers. Renderer factories can
          be part of both extension points and extensions. In most other aspects
          renderer factories are very similar to action factories.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Error handler factory</term>
        <listitem>
          <para>
          An <interfacename docapi="net.sf.basedb.util.extensions">ErrorHandlerFactory</interfacename>
          is an object that knows how to handle error that occur when executing extensions. 
          An error handler factory is defined as part of an extension point and handles all
          errors related to the extensions of that extension point. In most other aspects
          error handler factories are similar to renderer and action factories. If the 
          extension point doesn't define an error handler factory, the system will 
          select a default that only writes a message to the log file
          <classname docapi="net.sf.basedb.util.extensions">LoggingErrorHandlerFactory</classname>
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term>Client context</term>
        <listitem>
          <para>
          A <classname docapi="net.sf.basedb.util.extensions">ClientContext</classname>
          is an object which contains information about the current user session.
          It is for example, possible to get information about the logged in
          user, the currently active item, etc.
          </para>
          
          <para>
          In the BASE web client the context is always a 
          <classname docapi="net.sf.basedb.clients.web.extensions">JspContext</classname>.
          Wherever a <classname>ClientContext</classname> object is provided as a 
          parameter it is always safe to cast it to a <classname>JspContext</classname> 
          object. Extension points in the core usually use a 
          <classname>ClientContext</classname>.
          </para>
          
          <para>
          The context can also be used by an extension to request that a specific
          javascript or stylesheet file should be included in the HTML code.
          </para>
        </listitem>
      </varlistentry>
      
      </variablelist>
      
      
    </sect2>
  </sect1>
  
  <sect1 id="extensions_developer.helloworld">
    <?dbhtml filename="helloworld.html" ?>
    <title>Hello world as an extension</title>
    
    <para>
      We will use the classical Hello world as the first simple example
      of an extension. This extension will add a new menu item in the
      menu which displays a popup with the text "Hello world!" when 
      selected. 
    </para>
    
    <orderedlist>
      <listitem>
      <para>
      Start by creating an empty directory in some suitable
      location on your hard disk. Inside this directory, create two more
      directories <filename>META-INF</filename> and 
      <filename>resources</filename>. 
      </para>
      </listitem>
      
      <listitem>
      <para>
      Copy the XML code below and save it to <filename>META-INF/extensions.xml</filename>
      in your newly created directory. It is important that you get the filename
      correct.
      </para>
      
      <programlisting language="xml">
<![CDATA[
<?xml version="1.0" encoding="UTF-8" ?>
<extensions xmlns="http://base.thep.lu.se/extensions.xsd">
   <extension
      id="net.sf.basedb.clients.web.menu.extensions.helloworld"
      extends="net.sf.basedb.clients.web.menu.extensions"
      >
      <index>1</index>
      <about safe-scripts="1">
         <name>Hello world</name>
         <description>
            The very first extensions example. Adds a "Hello world"
            menu item that displays "Hello world" in a javascript
            popup when selected.
         </description>
      </about>
      <action-factory>
         <factory-class>  
            net.sf.basedb.clients.web.extensions.menu.FixedMenuItemFactory
         </factory-class>
         <parameters>
          <id>hello-world</id>
            <title>Hello world!</title>
            <tooltip>This is to test the extensions system</tooltip>
            <icon>/images/info.png</icon>
            <script>~/hello.js</script>
         </parameters>
      </action-factory>
   </extension>
</extensions>
]]>
</programlisting>
      <para>
        This file is the most important one when creating extensions
        since it is used to tell BASE about the extensions (and
        plug-ins) in the package. See below for more information.
      </para>
      </listitem>
      
      <listitem>
      <para>
      Copy the javascript code below and save it to <filename>resources/hello.js</filename>
      in your newly created directory. Once again, it is important that the filename
      is correct.
      </para>
      <programlisting language="javascript">
<![CDATA[
var HelloWorld = function()  
{  
   var hello = {};  
    
    /** 
       Executed once when the page is loaded. Typically 
       used to bind events to fixed control elements. 
    */  
    hello.initMenuItems = function()  
    {  
       // Bind event handlers the menu items.   
       // First parameter is the ID of the menu item  
       // Second parameter is the event to react to (=click)  
       // Last parameter is the function to execute  
       Events.addEventHandler('hello-world', 'click', hello.helloWorld);  
    }  
      
    // Show 'Hello world' message
    hello.helloWorld = function(event)  
    {  
       alert('Hello world');
    }  
     
    return hello;  
}();  
      
//Register the page initializer method with the BASE core  
Doc.onLoad(HelloWorld.initMenuItems);  
]]>
</programlisting>
      </listitem>
    
      <listitem>
      <para>
      Create a JAR package containing the two directories and files
      you have created. It is important the the subdirectory structure
      inside the JAR file is rooted at the first empty directory you created.
      </para>
      
        <literallayout>
<filename class="directory">META-INF/</filename>
<filename>META-INF/extensions.xml</filename>
<filename class="directory">resources/</filename>
<filename>resources/hello.js</filename>
        </literallayout>
      
      <para>
        Copy the JAR file to the the <filename>plugins.dir</filename>
        directory for your BASE installation.
      </para>
      </listitem>
    
      <listitem>
      <para>
        Log in to BASE and install the extension by going through the 
        installation wizard at <menuchoice>
            <guimenu>Administrate</guimenu>
            <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
            <guimenuitem>Overview</guimenuitem>
          </menuchoice>.
        When the extension has been installed you should have a new 
        menu item:
        <menuchoice>
          <guimenu>Extensions</guimenu>
          <guimenuitem>Hello world!</guimenuitem>
        </menuchoice>
        which pops up a message in a Javascript window.
        
      </para>
      <note>
        <para>
        You may have to logout and login again to see the new menu item.
        </para>
      </note>
      </listitem>
    
    </orderedlist>
    
    <sect2 id="extensions_developer.extensions.xml">
      <title>The extensions.xml file</title>
    
    <para>
      The <sgmltag class="starttag">extensions</sgmltag> tag is the root
      tag and is needed to set up the namespace and schema validation.
    </para>
    
    <para>
      The <sgmltag class="starttag">extension</sgmltag> defines a new
      extension. It must have an <sgmltag>id</sgmltag> attribute that
      is unique among all installed extensions and an <sgmltag>extends</sgmltag> 
      attribute which id the ID of the extension point. For the <sgmltag>id</sgmltag>
      attribute we recommend using the same naming conventions as for java
      packages. See <ulink 
      url="http://www.oracle.com/technetwork/java/codeconventions-135099.html">Java naming
      conventions from Oracle</ulink>.
    </para>
    
    <para>
      The <sgmltag class="starttag">about</sgmltag> tag is optional and
      can be used to provide meta information about the extension. We
      recommend that all extensions are given at least a
      <sgmltag class="starttag">name</sgmltag>. Other supported subtags are:
      
      <itemizedlist>
        <listitem><sgmltag class="starttag">description</sgmltag></listitem>
        <listitem><sgmltag class="starttag">version</sgmltag></listitem>
        <listitem><sgmltag class="starttag">copyright</sgmltag></listitem>
        <listitem><sgmltag class="starttag">contact</sgmltag></listitem>
        <listitem><sgmltag class="starttag">email</sgmltag></listitem>
        <listitem><sgmltag class="starttag">url</sgmltag></listitem>
      </itemizedlist>
      
      <tip>
        <title>Global about tag</title>
        
        <para>
          <sgmltag class="starttag">about</sgmltag> tag can also be specified as a
          first-level tag (eq. as a child to <sgmltag class="starttag">extensions</sgmltag>).
          This can be useful when an XML file defines more than one extension
          and you don't want to repeat the same information for every extension.
          You can still override the information for specific extensions by including
          new values in the extension's <sgmltag class="starttag">about</sgmltag>
          tag.
        </para>
      </tip>
      
      <tip>
        <title>Start out in disabled state</title>
        
        <para>
          The <sgmltag class="starttag">about</sgmltag> tag can be used to specify
          that an extension should start out in disabled state. This can be useful
          if there are multiple variants of an extension or if some extensions
          are considered "advanced mode" and only should be enabled after some
          serious thinking. To use this feature, simply set <code>&lt;about disabled="1"&gt;</code>
          in the XML file.
        </para>
      </tip>
    </para>
    
    <para>
      The <sgmltag class="starttag">action-factory</sgmltag> tag is required and
      so is the <sgmltag class="starttag">factory-class</sgmltag> subtag. It tells
      the extension system which factory to use for creating actions. The
      <classname docapi="net.sf.basedb.clients.web.extensions.menu">FixedMenuItemFactory</classname>
      is a very simple factory that is shipped with BASE. This factory always creates the same
      menu item, no matter what. Another factory for menu items is the 
      <classname docapi="net.sf.basedb.clients.web.extensions.menu">PermissionMenuItemFactory</classname>
      which can create menu items that depends on the logged in user's permissions. It is
      for example, possible to hide or disable the menu item if the user doesn't have enough
      permissions. If none of the supplied factories suits you it is possible to 
      supply your own implementation. More about this later.
    </para>
    
    <para>
      The <sgmltag class="starttag">parameters</sgmltag> subtag is used to
      provide initialisation parameters to the factory. Different factories 
      supports different parameters and you will have to check the javadoc documentation
      for each factory to get information about which parameters that are supported.
    </para>
    
    <tip>
      <para>
        In case the factory is poorly documented you can always assume that public
        methods the start with <code>set</code> and take a single <classname>String</classname>
        as an argument can be used as a parameter. The parameter tag to use should
        be the same as the method name, minus the <code>set</code> prefix and with
        the first letter in lowercase. For example, the method 
        <methodname>setIcon(String icon)</methodname> corresponds to the 
        <sgmltag class="starttag">icon</sgmltag> parameter.
      </para>
    </tip>
    
    <note>
      <title>Content security policy and inline javascript</title>
      <para>
        The Hello World example requires quite a lot of code and it
        would have been tempting to skip the <filename>hello.js</filename>
        file and simply add 
        
        <code><sgmltag class="starttag">onclick</sgmltag>alert('Hello world')<sgmltag class="endtag">onclick</sgmltag></code>
        
        to the <sgmltag class="starttag">parameters</sgmltag> section in the
        <filename>extensions.xml</filename> file. However, BASE is by default
        configured to block all inline JavaScript since it opens up for
        cross-site scripting attacks. It is possible to relax this policy
        but it is nothing we recommend. See
        <xref linkend="appendix.web.xml.csp-filter" /> for more information.
      </para>
      
      <para>
        The real code examples uses a different design with pure HTML that is 
        generated dynamically and a fixed javascript file that attaches event
        handlers when the page has been loaded and should be compatible with the
        stricter security policy.
      </para>
    </note>
    
    </sect2>
    
    <sect2 id="extensions_developer.extend_multiple">
      <title>Extending multiple extension points with a single extension</title>
      
      <para>
        A single extension can extend multiple extension points as long as their
        action classes are compatible. This is for, for example, the case when 
        you want to add a button to more than one toolbar.        
        To do this use the <sgmltag class="starttag">extends</sgmltag>
        tag with multiple <sgmltag class="starttag">ref</sgmltag> tags. 
        You can skip the <sgmltag class="attribute">extends</sgmltag> 
        attribute in the main tag.
      </para>
    <programlisting language="xml">
<![CDATA[
<extension
   id="net.sf.basedb.clients.web.menu.extensions.history-edit"
   >
   <extends>
      <ref index="2">net.sf.basedb.clients.web.tabcontrol.edit.sample</ref>
      <ref index="2">net.sf.basedb.clients.web.tabcontrol.edit.extract</ref>
   </extends>
   ...
</extension>
]]>
</programlisting>
      
      <para>
        This is a feature of the XML format only. Behind the scenes two extensions will
        be created (one for each extension point). The extensions will share the same
        action and renderer factory instances. Since the id for an extension must be unique
        a new id will be generated by combining the original id with the parts of the id's from 
        the extension points. 
      </para>
      
    </sect2>
  </sect1>


  <sect1 id="extensions_developer.factories">
    <?dbhtml filename="factories.html" ?>
    <title>Custom action factories</title>

    <para>
      Some times the factories shipped with BASE are not enough, and you
      may want to provide your own factory implementation. In this case you will
      have to create a class that implements the 
      <interfacename docapi="net.sf.basedb.util.extensions">ActionFactory</interfacename>
      interface. Here is a very simple example that does the same as the 
      previous "Hello world" example.
    </para>
    
    <programlisting language="java">
<![CDATA[
package net.sf.basedb.examples.extensions;

import net.sf.basedb.clients.web.extensions.JspContext;
import net.sf.basedb.clients.web.extensions.menu.MenuItemAction;
import net.sf.basedb.clients.web.extensions.menu.MenuItemBean;
import net.sf.basedb.util.extensions.ActionFactory;
import net.sf.basedb.util.extensions.InvokationContext;

/**
   First example of an action factory where eveything is hardcoded.
   @author nicklas
*/
public class HelloWorldFactory
   implements ActionFactory<MenuItemAction>
{

   private MenuItemAction[] helloWorld;

   // A public, no-argument constructor is required
   public HelloWorldFactory()
   {
      helloWorld = new MenuItemAction[1];
   }
   
   // Return true enable the extension, false to disable it
   public boolean prepareContext(
      InvokationContext<? super MenuItemAction> context) 
   {
      JspContext jspContext = (JspContext)context.getClientContext();
      String home = jspContext.getHome(context.getExtension());
      jspContext.addScript(home + "/hello.js");
      return true;
   }

   // An extension may create one or more actions
   public MenuItemAction[] getActions(
      InvokationContext<? super MenuItemAction> context) 
   {
      // This cast is always safe with the web client
      JspContext jspContext = (JspContext)context.getClientContext();
      if (helloWorld[0] == null)
      {
         MenuItemBean bean = new MenuItemBean();
         bean.setId("hello-factory");
         bean.setTitle("Hello factory world!");
         bean.setIcon(jspContext.getRoot() + "/images/info.gif");
         helloWorld[0] = bean;
      }
      return helloWorld;
   }
}
]]>
</programlisting>

    <para>
      And here are the XML and JavaScript files that goes with it.
    </para>

    <programlisting language="xml">
<![CDATA[
<?xml version="1.0" encoding="UTF-8" ?>
<extensions xmlns="http://base.thep.lu.se/extensions.xsd">
   <extension
      id="net.sf.basedb.clients.web.menu.extensions.helloworldfactory"
      extends="net.sf.basedb.clients.web.menu.extensions"
      >
      <index>2</index>
      <about>
         <name>Hello factory world</name>
         <description>
            A "Hello world" variant with a custom action factory.
            Everything is hard-coded into the factory.
         </description>
      </about>
      <action-factory>
         <factory-class>
            net.sf.basedb.examples.extensions.HelloWorldFactory
         </factory-class>
      </action-factory>
   </extension>
</extensions>
]]>
</programlisting>
    <programlisting language="javascript">
<![CDATA[
var HelloWorldFactory = function()  
{  
   var hello = {};  
    
    /** 
       Executed once when the page is loaded. Typically 
       used to bind events to fixed control elements. 
    */  
    hello.initMenuItems = function()  
    {  
       // Bind event handlers the menu items.   
       // First parameter is the ID of the menu item  
       // Second parameter is the event to react to (=click)  
       // Last parameter is the function to execute  
       Events.addEventHandler('hello-factory', 'click', hello.helloFactoryWorld);  
    }  
      
    // Show 'Hello factory world' message
    hello.helloFactoryWorld = function(event)  
    {  
       alert('Hello factory world');
    }  
     
    return hello;  
}();  
      
//Register the page initializer method with the BASE core  
Doc.onLoad(HelloWorldFactory.initMenuItems);  
]]>
</programlisting>
    
    <para>
      To install this extension you need to put the compiled 
      <filename>HelloWorldFactory.class</filename>, the XML 
      and JavaScript files inside a JAR file. The XML file must be located at
      <filename>META-INF/extensions.xml</filename> the JavScript file
      at <filename>resources/hello.js</filename>, and the class
      file at <filename>net/sf/basedb/examples/extensions/HelloWorldFactory.class</filename>.
    </para>
    
    <para>
      The above example is a bit artificial and we have not gained anything.
      Instead, we have lost the ability to easily change the menu since everything is 
      now hardcoded into the factory. To change, for example the title, requires that 
      we recompile the java code. It would be more useful if we could make the factory
      configurable with parameters. The next example will make the icon
      and message configurable, and also include the name
      of the currently logged in user. For example: "Greetings &lt;name of 
      logged in user&gt;!". We'll also get rid of the onclick event handler
      and use proper event binding using javascript.
    </para>
    
    <programlisting language="java">
<![CDATA[
package net.sf.basedb.examples.extensions;

import net.sf.basedb.clients.web.extensions.AbstractJspActionFactory;
import net.sf.basedb.clients.web.extensions.menu.MenuItemAction;
import net.sf.basedb.clients.web.extensions.menu.MenuItemBean;
import net.sf.basedb.core.DbControl;
import net.sf.basedb.core.SessionControl;
import net.sf.basedb.core.User;
import net.sf.basedb.util.extensions.ClientContext;
import net.sf.basedb.util.extensions.InvokationContext;
import net.sf.basedb.util.extensions.xml.PathSetter;
import net.sf.basedb.util.extensions.xml.VariableSetter;

/**
   Example menu item factory that creates a "Hello world" menu item
   where the "Hello" part can be changed by the "prefix" setting in the
   XML file, and the "world" part is dynamically replaced with the name
   of the logged in user.
   
   @author nicklas
*/
public class HelloUserFactory 
   extends AbstractJspActionFactory<MenuItemAction>
{
   // The ID attribute of the <div> tag in the final HTML
   private String id;
 
   // To store the URL to the icon
   private String icon;
   
   // The default prefix is Hello
   private String prefix = "Hello";
   
   // A public, no-argument constructor is required
   public HelloUserFactory()
   {}
   
   /**
      Creates a menu item that displays: {prefix} {name of user}!
   */
   public MenuItemAction[] getActions( 
      InvokationContext<? super MenuItemAction> context) 
   {
      String userName = getUserName(context.getClientContext());
      MenuItemBean helloUser = new MenuItemBean();
      helloUser.setId(id);
      helloUser.setTitle(prefix + " " + userName + "!");
      helloUser.setIcon(icon);
      // Use 'dynamic' attributes for extra info that needs to be included
      // in the HTML
      setParameter("data-user-name", userName);
      setParameter("data-prefix", prefix);
      helloUser.setDynamicActionAttributesSource(this);
      return new MenuItemAction[] { helloUser };
   }

   /**
      Get the name of the logged in user.
   */
   private String getUserName(ClientContext context)
   {
      SessionControl sc = context.getSessionControl();
      DbControl dc = context.getDbControl();
      User current = User.getById(dc, sc.getLoggedInUserId());
      return current.getName();
   }
   
    /**
      Set the ID to use for the <div> tag. This is needed
      so that we can attach a 'click' handler to the menu item
      with JavaScript.
   */
   public void setId(String id)
   {
      this.id = id;
   }
   
   /**
      Sets the icon to use. Path conversion is enabled.
   */
   @VariableSetter
   @PathSetter
   public void setIcon(String icon)
   {
      this.icon = icon;
   }
   
   /**
      Sets the prefix to use. If not set, the
      default value is "Hello".
   */
   public void setPrefix(String prefix)
   {
      this.prefix = prefix == null ? "Hello" : prefix;
   }
}
]]>
</programlisting>
    
    <para>
      The are several new parts in this factory. The first is the <methodname>getUserName()</methodname>
      method which is called from <methodname>getActions()</methodname>. Note
      that the <methodname>getActions()</methodname> method always create
      a new <classname docapi="net.sf.basedb.clients.web.extensions.menu">MenuItemBean</classname>.
      It can no longer be cached since the title and javascript code depends on
      which user is logged in. 
    </para>
    
    <para>
      The second new part is the <methodname>setId()</methodname>, 
      <methodname>setIcon()</methodname> and
      <methodname>setPrefix()</methodname> methods.
      The extensions system uses java reflection to find the existance of
      the methods if <sgmltag class="starttag">id</sgmltag>,
      <sgmltag class="starttag">icon</sgmltag> and/or 
      <sgmltag class="starttag">prefix</sgmltag> tags are present
      in the <sgmltag class="starttag">parameters</sgmltag> tag for a factory,
      the methods are automatically called with the value inside the tag 
      as it's argument.
    </para>
    
    <para>
      The <classname docapi="net.sf.basedb.util.extensions.xml">VariableSetter</classname> 
      and <classname docapi="net.sf.basedb.util.extensions.xml">PathSetter</classname> 
      annotations on the <methodname>setIcon()</methodname> are used to enable 
      "smart" convertions of the value. Note that in the 
      XML file you only have to specify <filename>/images/info.png</filename>
      as the URL to the icon, but in the hardcoded factory you have to 
      do: <code>jspContext.getRoot() + "/images/info.png"</code>. In this case, 
      it is the <classname>PathSetter</classname> which automatically adds the 
      the JSP root directory to all URL:s starting with /. The 
      <classname>VariableSetter</classname> can do the same thing but you would have to use
      <code>$ROOT$</code> instead. Eg. <code>$ROOT$/images/info.png</code>. The
      <classname>PathSetter</classname> only looks at the first characteer,
      while the <classname>VariableSetter</classname> looks in the entire string.
    </para>
    
    <para>
      The third new part is the use of dynamic action attributes. These
      are extra attributes that have not been defined by the <classname>Action</classname>
      interface. To set a dynamic attribute we call the
      <methodname>setParameter()</methodname> method and then 
      <methodname>MenuItemBean.setDynamicActionAttributesSource()</methodname>
      The dynamic attributes are a simple way to output data to
      the HTML that is later needed by scripts. In this case, the generated
      HTML may look something like this:
    </para>
    
    <programlisting language="html">
<![CDATA[
<div id="greetings-user" data-user-name="..." data-prefix="Greetings" ... >
...
</div>
]]>
</programlisting>
    
    <para>
      Here is an example of an extension configuration that can be used
      with the new factory. Notice that the <sgmltag class="starttag">about</sgmltag>
      tag now include <code>safe-scripts="1"</code> attribute. This is a way
      for the devloper to tell the extensions installation wizard that the extensions
      doesn't use any unsafe code and no warning will be displayed when installing the
      extensions.
    </para>
    
    <programlisting language="xml">
<![CDATA[
<extensions xmlns="http://base.thep.lu.se/extensions.xsd">
   <extension
      id="net.sf.basedb.clients.web.menu.extensions.hellouser"
      extends="net.sf.basedb.clients.web.menu.extensions"
      >
      <index>3</index>
      <about safe-scripts="1">
         <name>Greetings user</name>
         <description>
            A "Hello world" variant with a custom action factory
            that displays "Greetings {name of user}" instead. We also
            make the icon configurable.
         </description>
      </about>
      <action-factory>
         <factory-class>
            net.sf.basedb.examples.extensions.HelloUserFactory
         </factory-class>
         <parameters>
          <id>greetings-user</id>
            <prefix>Greetings</prefix>
            <icon>/images/take_ownership.png</icon>
            <script>~/scripts/menu-items.js</script>
         </parameters>
      </action-factory>
   </extension>
</extensions>
]]>
</programlisting>
    
    <para>
    And the <filename>menu-items.js</filename> JavaScript file:
    </para>
    <programlisting language="javascript">
<![CDATA[
var HelloWorldMenu = function()
{
   var menu = {};

   /**
      Executed once when the page is loaded. Typically
      used to bind events to fixed control elements.
   */
   menu.initMenuItems = function()
   {
      // Bind event handlers the menu items. 
      // First parameter is the ID of the menu item
      // Second parameter is the event to react to (=click)
      // Last parameter is the function to execute
      Events.addEventHandler('greetings-user', 'click', menu.greetingsUser);
   }

   // Get the dynamic attributes defined in extensions.xml 
   // and generate an alert message
   menu.greetingsUser = function(event)
   {
      var userName = Data.get(event.currentTarget, 'user-name');
      var prefix = Data.get(event.currentTarget, 'prefix');
      alert(prefix + ' ' + userName + '!');
   }

   return menu;
}();

//Register the page initializer method with the BASE core
Doc.onLoad(HelloWorldMenu.initMenuItems);
]]>
</programlisting>
    
    <note>
      <title>Be aware of multi-threading issues</title>
      <para>
        When you are creating custom action and renderer factories be 
        aware that multiple threads may use a single factory instance 
        at the same time. Action and renderer objects only needs to 
        be thread-safe if the factories re-use the same objects.
      </para>
    </note>
    
  </sect1>

  <sect1 id="extensions_developer.resources">
    <?dbhtml filename="resources.html" ?>
    <title>Custom images, JSP files, and other resources</title>

    <para>
      Some times your extension may need other resources. It can for
      for example be an icon, a javascript file, a JSP file or something
      else. Fortunately this is very easy. You need to put the extension
      in a JAR file. As usual the extension definition XML file should be
      at <filename>META-INF/extensions.xml</filename>. Everything you put in
      the JAR file inside the <filename>resources/</filename> directory
      will automatically be extracted by the extension system to a directory
      on the web server. Here is another "Hello world" example which uses a
      custom JSP file to display the message. There is also a custom icon.
    </para>
    
    <programlisting language="xml">
<![CDATA[
<extensions xmlns="http://base.thep.lu.se/extensions.xsd">
   <extension
      id="net.sf.basedb.clients.web.menu.extensions.hellojspworld"
      extends="net.sf.basedb.clients.web.menu.extensions"
      >
      <index>4</index>
      <about safe-scripts="1" safe-resources="1">
         <name>Hello JSP world</name>
         <description>
            This example uses a custom JSP file to display the
            "Hello world" message instead of a javascript popup.
         </description>
      </about>
      <action-factory>
         <factory-class>
            net.sf.basedb.clients.web.extensions.menu.FixedMenuItemFactory
         </factory-class>
         <parameters>
            <title>Hello JSP world!</title>
            <tooltip>Opens a JSP file with the message</tooltip>
            <data-url>$HOME$/hello_world.jsp?ID=$SESSION-ID$</data-url>
            <data-popup>HelloJspWorld, 400, 300</data-popup>
            <icon>~/images/world.png</icon>
         </parameters>
      </action-factory>
   </extension>
</extensions>
]]>
</programlisting>
    
    <para>
      The JAR file should have have the following contents:
    </para>
    
    <programlisting>
META-INF/extensions.XML
resources/hello_world.jsp
resources/images/world.png
</programlisting>
    
    <para>
      When this extension is installed the <filename>hello_world.jsp</filename>
      and <filename>world.png</filename> files are automatically extracted
      to the web servers file system. Each extension is given a unique 
      <code>HOME</code> directory to make sure that extensions doesn't interfere
      with each other. The URL to the home directory is made available in the
      <varname>$HOME$</varname> variable. All factory settings that have
      been annotated with the <interfacename 
      docapi="net.sf.basedb.util.extensions.xml">VariableSetter</interfacename>
      will have their values scanned for <code>$HOME$</code> which is replaced
      with the real URL. It is also possible to use the <varname>$ROOT$</varname>
      variable to get the root URL for the BASE web application. Never use
      <code>/base/...</code> since users may install BASE into another 
      path.
    </para>
    
    <para>
      The tilde (~) in the <sgmltag class="starttag">icon</sgmltag> tag value
      is also replaced with the <code>HOME</code> path. Note that this kind of
      replacement is only done on factory settings that have been annotated
      with the <classname docapi="net.sf.basedb.util.extensions.xml">PathSetter</classname>
      annotation and is only done on the first character.
    </para>
    
    <para>
      The <code>safe-resources="1"</code> attribute in the <sgmltag class="starttag">about</sgmltag>
      tag is used to tell BASE that all resource files doesn't use inline scripts or event handlers.
      This is the default setting and don't have to be included. On the other hand, 
      if <code>safe-resources="0"</code> is specified BASE uses a less restrictive content
      security policy for that extension that allows the use of inline scripts. This setting
      is not recommended but can be useful during a transition phase while the extensions code
      is being updated.
    </para>
    
    <note>
      <para>
      Unfortunately, the custom JSP file can't use classes that
      are located in the extension's JAR file. The reason is that the
      JAR file is not known to Tomcat and Tomcat will not look in the
      <filename>plugins.dir</filename> folder to
      try to find classes. There are currently two possible workarounds:
      </para>
      
      <itemizedlist>
      <listitem>
        <para>
        Place classes needed by JSP files in a separate JAR file that
        is installed into the <filename>WEB-INF/lib</filename> folder. 
        The drawback is that this requires a restart of Tomcat.
        </para>
      </listitem>
      
      <listitem>
        <para>
        Use an X-JSP file instead. This is an experimental feature. See
        <xref linkend="extensions_developer.resources.xjsp" /> for more 
        information.
        </para>
      </listitem>
      </itemizedlist>
    </note>
    
    <sect2 id="extensions_developer.resources.scripts">
      <title>Javascript and stylesheets</title>
      
      <para>
        It is possible for an extension to use a custom javascript or stylesheet.
        However, this doesn't happen automatically and may not be enabled
        for all extension points. If an extension needs this functionality
        the action factory or renderer factory must call 
        <methodname>JspContext.addScript()</methodname> or 
        <methodname>JspContext.addStylesheet()</methodname> from the 
        <methodname>prepareContext()</methodname> method.
      </para>
      
      <para>
        The <classname 
        docapi="net.sf.basedb.clients.web.extensions">AbstractJspActionFactory</classname>
        and <classname 
        docapi="net.sf.basedb.clients.web.extensions">AbstractJspRendererFactory</classname>
        factory can do this. All factories shipped with BASE extends one of those
        classes and we recommend that custom-made factories also does this.
      </para>
      
      <para>
        Factories that are extending one of those two classes can use
        <sgmltag class="starttag">script</sgmltag> and 
        <sgmltag class="starttag">stylesheet</sgmltag> tags in the 
        <sgmltag class="starttag">parameters</sgmltag> section for an
        extensions. Each tag may be used more than one time. The
        values are subject to path and variable substitution.
      </para>
      
      <programlisting language="xml">
<![CDATA[
<action-factory>
   <factory-class>
      ... some factory class ...
   </factory-class>
   <parameters>
      <script>~/scripts/custom.js</script>
      <stylesheet>~/css/custom.css</stylesheet>
      ... other parameters ...
   </parameters>
</action-factory>
]]>
</programlisting>
      
      <para>
        If scripts and stylesheets has been added to the JSP context
        the extension system will, <emphasis>in most cases</emphasis>, 
        include the proper HTML to link in the requested scripts and/or 
        stylesheet.
      </para>
      
      <note>
        <title>Use UTF-8 character encoding</title>
        <para>
          The script and stylesheet files should use use UTF-8 character encoding.
          Otherwise they may not work as expected in BASE.
        </para>
      </note>
      
      <note>
        <title>All extension points doesn't support custom scripts/stylesheets</title>
        <para>
          In some cases the rendering of the HTML page has gone to far
          to make is possible to include custom scripts and stylesheets.
          This is for example the case with the extensions menu. Always
          check the documentation for the extension point if scripts
          and stylesheets are supported or not.
        </para>
      </note>
    </sect2>
    
    <sect2 id="extensions_developer.resources.xjsp">
      <title>X-JSP files</title>
      
      <para>
        The drawback with a custom JSP file is that it is not possible to
        use classes from the extension's JAR file in the JSP code. The reason 
        is that the JAR file is not known to Tomcat and Tomcat will not look 
        in the <filename>plugins.dir</filename> folder to try to find 
        classes.
      </para>
      
      <para>
        One workaround is to place classes that are needed by the JSP files
        in a separate JAR file that is placed in <filename>WEB-INF/lib</filename>.
        The drawback with this is that it requires a restart of Tomcat. It is
        also a second step that has to be performed manually by the person 
        installing the extension and is maybe forgotten when doing an update.
      </para>
      
      <para>
        Another workaround is to use an X-JSP file. This is simply a regular
        JSP file that has a <code>.xjsp</code> extension instead of <code>.jsp</code>.
        The <code>.xjsp</code> extension will trigger the use of a different
        compiler that knows how to include the extension's JAR file in the class
        path.
      </para>
      
      <note>
        <title>X-JSP is experimental</title>
        <para>
          The X-JSP compiler depends on functionality that is internal to
          Tomcat. The JSP compiler is not part of any open specification
          and the implementation details may change at any time. This means
          that the X-JSP compiler may or may not work with future versions
          of Tomcat. We have currently tested it with Tomcat 8.0.21 only.
          It will most likely not work with other servlet containers.
        </para>
        
        <para>
          Adding support for X-JSP requires that a JAR file with the 
          X-JSP compiler is installed into Tomcat's internal <filename>/lib</filename>
          directory. It is an optional step and not all BASE installations
          may have the compiler installed. See <xref linkend="plugins.installation.xjspcompiler" />.
        </para>
      </note>
      
    </sect2>
  </sect1>
  
  <sect1 id="extensions_developer.renderer">
    <?dbhtml filename="renderer.html" ?>
    <title>Custom renderers and renderer factories</title>

    <para>
      It is always the responsibility of the extension point to
      render an action. The need for custom renderers is typically
      very small, at least if you want your extensions to blend into
      the look and feel of the BASE web client. Most customizations can
      be probably be handled by stylesheets and images. That said,
      you may still have a reason for using a custom renderer.
    </para>
    
    <para>
      Renderer factories are not very different from action factories.
      They are specified in the same way in the XML file and uses the
      same method for initialisation, including support for path
      conversion, etc. The difference is that you use a
      <sgmltag class="starttag">renderer-factory</sgmltag> tag
      instead of an <sgmltag class="starttag">action-factory</sgmltag>
      tag.
    </para>

    <programlisting language="xml">
<![CDATA[
<renderer-factory>
   <factory-class>
      ... some factory class ...
   </factory-class>
   <parameters>
      ... some parameters ...
   </parameters>
</renderer-factory>
]]>
</programlisting>

    <para>
      A <interfacename docapi="net.sf.basedb.util.extensions"
      >RendererFactory</interfacename> also has a <methodname>prepareContext()</methodname>
      method that can be used to tell the web client about any scripts or stylesheets
      the extension needs. If your renderer factory extends the <classname 
        docapi="net.sf.basedb.clients.web.extensions">AbstractJspRendererFactory</classname>
      class you will not have to worry about this since you can configure
      scripts and stylesheets in the XML file.
    </para>
    
    <para>
      A render factory must also implement the <methodname>getRenderer()</methodname> 
      which should return a <interfacename docapi="net.sf.basedb.util.extensions"
      >Renderer</interfacename> instance. The extension system will then call
      the <methodname>Renderer.render()</methodname> method to render an action.
      This method may be called multiple times if the extension created more than
      one action.
    </para>
    
    <para>
      The renderers responsibility is to generate the HTML
      that is going to be sent to the web client. To do this it needs
      access to the <classname 
      docapi="net.sf.basedb.clients.web.extensions">JspContext</classname> 
      object that was passed to the renderer factory. Here is a simple
      outline of both a renderer factory and renderer. 
    </para>
    
    <programlisting language="java">
<![CDATA[
// File: MyRendererFactory.java
public class MyRendererFactory
   extends AbstractJspRendererFactory<MyAction>
{

   public MyRendererFactory()
   {}

   @Override
   public MyRenderer getRenderer(InvokationContext context)
   {
      return new MyRenderer((JspContext)context.getClientContext());
   }
}

// File: MyRenderer.java
public class MyRenderer
   implements Renderer<MyAction>
{

   private final JspContext context;
   public MyRenderer(JspContext context)
   {
      this.context = context;
   }

   /**
      Generates HTML (unless invisible): 
      <a class="[clazz]" style="[style]" href="[href]">[title]</a>
   */
   public void render(MyAction action)
   {
      if (!action.isVisible()) return;
      Writer out = context.getOut();
      try
      {
         out.write("<a");
         if (action.getClazz() != null) 
         {
            out.write(" class=\"" + action.getClazz() + "\"");
         }
         if (action.getStyle() != null) 
         {
            out.write(" style=\"" + action.getStyle() + "\"");
         }
         if (action.getHref() != null) 
         {
            out.write(" href=\"" + action.getHref() + "\"");
         }
         out.write(">");
         out.write(HTML.encodeTags(action.getTitle()));
         out.write("</a>\n");
      }
      catch (IOException ex)
      {
         throw new RuntimeException(ex);
      }
   }
}
]]>
</programlisting>
  </sect1>
  
  <sect1 id="extensions_developer.extension_points">
    <?dbhtml filename="extensionpoints.html" ?>
    <title>Extension points</title>
    
    <para>
      The BASE web client ships with a number of predefined extension
      points. Adding more extension points to the existing web client
      requires some minor modifications to the regular JSP files. But this
      is not what this chapter is about. This chapter is about defining new
      extension points as part of an extension. It is nothing magical about
      this and the process is the same as for the regular extension points in
      the web client.
    </para>
    
    <para>
      The first thing you need to do is to start writing the 
      XML definition of the extension point. Here is an example
      from the web client:
    </para>
    
    <programlisting language="xml">
<![CDATA[
<extensions
   xmlns="http://base.thep.lu.se/extensions.xsd"
   >
   <extension-point
      id="net.sf.basedb.clients.web.menu.extensions"
      >
      <action-class>net.sf.basedb.clients.web.extensions.menu.MenuItemAction</action-class>
      <name>Menu: extensions</name>
      <description>
         Extension point for adding extensions to the 'Extensions' menu.
         Extensions should provide MenuItemAction instances. The rendering
         is internal and extensions can't use their own rendering factories.
         The context will only include information about the currently logged
         in user, not information about the current page that is displayed.
         The reason for this is that the rendered menu is cached as a string
         in the user session. The menu is not updated on every page request.
         As of BASE 3.3, this extension point also support custom scripts and
         stylesheets.
      </description>
   </extension-point>
</extensions>
]]>
</programlisting>
    
    <para>
      The <sgmltag class="starttag">extensions</sgmltag> tag is the root tag and 
      is needed to set up the namespace and schema validation.
    </para>
    
    <para>
      The <sgmltag class="starttag">extension-point</sgmltag> defines a new
      extension point. It must have an <sgmltag>id</sgmltag> attribute that
      is unique among all installed extension points. We recommend using 
      the same naming conventions as for java packages. See <ulink 
      url="http://www.oracle.com/technetwork/java/codeconventions-135099.html">Java naming
      conventions from Oracle</ulink>.
    </para>
    
    <note>
      <title>Document the extension point!</title>
      <para>
        The <sgmltag class="starttag">name</sgmltag> and 
        <sgmltag class="starttag">description</sgmltag> tags are optional,
        but we strongly recommend that values are provided.
        The description tag should be used to document the extension
        point. Pay special attention to the support (or lack of
        support) for custom scripts, stylesheets and renderers.
      </para>
    </note>
    
    <para>
      The <sgmltag class="starttag">action-class</sgmltag> defines the
      interface or class that extensions must provide to the extension
      point. This must be a class or interface that is a subclass
      of the <interfacename 
      docapi="net.sf.basedb.util.extensions">Action</interfacename>
      interface. We generally recommend that interfaces are used since
      this gives more implementation flexibility for action factories, but
      a regular class may work just as well. 
    </para>
      
    <para>
      The action class is used to carry information about the action,
      such as a title, which icon to use, a tooltip text, etc. The action class may
      be as simple or complex as you like.
    </para>
      
    <note>
      <title>Web client extension points</title>
      <para>
        This is a note for the core developers. Extension points that
        are part of the web client should always define the action as
        an interface. We recommend that <code>getId()</code>, <code>getClazz()</code>
        and <code>getStyle()</code> attributes are always included if this makes 
        sense. It is usually also a good idea to include <code>isVisible()</code>
        and <code>isEnabled()</code> attributes.
      </para>
    </note>
      
    <para>
      Now, if you are a good citizen you should also provide at least
      one implementation of an action factory that can create the 
      objects of the desired type of action. The factory should
      of course be configurable from the XML file.
    </para>
    
    <para>
      If you are lazy or if you want to immediately start testing the JSP code
      for the extension point, it may be possible to use one of the debugger action
      factories in the <package>net.sf.basedb.util.extensions.debug</package>
      pacakge.
    </para>
    
    <itemizedlist>
    <listitem>
      <para>
      <classname 
      docapi="net.sf.basedb.util.extensions.debug">ProxyActionFactory</classname>:
      This action factory can only be used if your action class is an interface
      and all important methods starts with <code>get</code> or <code>is</code>.
      The proxy action factory uses Java reflection to create a dynamic
      proxy class in runtime. It will map all <code>getX()</code> and <code>isY()</code> 
      methods to retreive the values from the corresponding parameter in the XML file. 
      For example, <methodname>getIcon()</methodname> will retrieve the value
      of the <sgmltag class="starttag">icon</sgmltag> tag and 
      <methodname>isVisible()</methodname> from the <sgmltag 
      class="starttag">visible</sgmltag>. The factory is smart enough to convert
      the string to the correct return value for <type>int</type>, <type>long</type>, 
      <type>float</type>, <type>double</type> and <type>boolean</type> data types and 
      their corresponding object wrapper types, if this is needed.
      </para>
    </listitem>
    
    <listitem>
      <para>
      <classname 
      docapi="net.sf.basedb.util.extensions.debug">BeanActionFactory</classname>:
      This action factory can be used if you have created a bean-like 
      class that implements the desired action class. The factory will
      create an instance of the class specified by the 
      <sgmltag class="starttag">beanClass</sgmltag> parameter. The factory
      will then use Java reflection to find <code>set</code> method
      for the other parameters. If there is a parameter <sgmltag class="starttag">icon</sgmltag>
      the factory first looks for a <methodname>setIcon(String)</methodname>
      method. If it can't find that it will see if there is a <methodname>getIcon()</methodname>
      method which has a return type, T. If so, a second attempt is made to find
      a <methodname>setIcon(T)</methodname> method. The factory is smart enough 
      to convert the string value from the XML file to the correct return value
       for <type>int</type>, <type>long</type>, <type>float</type>, 
      <type>double</type> and <type>boolean</type> data types and their 
      corresponding object wrapper types, if this is needed.
      </para>
    </listitem>
    
    </itemizedlist>


    <para>
      It is finally time to write the JSP code that actually uses the
      extension point. It is usually not very complicated. Here is 
      an exemple which lists snippets from a JSP file:
    </para>

    <programlisting>
<![CDATA[
// 1. We recommend using the extensions taglib (and the BASE core taglib)
<%@ taglib prefix="ext" uri="/WEB-INF/extensions.tld" %>
<%@ taglib prefix="base" uri="/WEB-INF/base.tld" %>

// 2. Prepare the extension point
SessionControl sc = Base.getExistingSessionControl(pageContext, true);
JspContext jspContext = ExtensionsControl.createContext(sc, pageContext);
ExtensionsInvoker invoker = ExtensionsControl.useExtensions(jspContext, 
   "my.domain.name.extensionspoint");

// 3. Output scripts and stylesheets
<base:page title="My new extension point">
   <base:head>
      <ext:scripts context="<%=jspContext%>" />
      <ext:stylesheets context="<%=jspContext%>" />
   </base:head>
   <base:body>
   ....

// 4a. Using a taglib for rendering with the default renderer
<ext:render extensions="<%=invoker%>" context="<%=jspContext%>" />

// 4b. Or, use the iterator and a more hard-coded approach
<%
Iterator it = invoker.iterate();
while (it.hasNext())
{
   MyAction action = (MyAction)it.next();
   String html = action.getTitle() +
    ....
   out.write(html);
}
%>
]]>
</programlisting>

    <sect2 id="extensions_developer.error_handler">
      <title>Error handlers</title>
      
      <para>
        An extension points may define a custom error handler. If not, the
        default error handler is used which simply writes a message to the
        log file. If you want to use a different error handler, create
        a <sgmltag class="starttag">error-handler-factory</sgmltag> tag
        inside the extension point definition. The <sgmltag 
        class="starttag">factory-class</sgmltag> is a required subtag and
        must specify a class with a public no-argument constructor that
        implements the 
        <interfacename docapi="net.sf.basedb.util.extensions">ErrorHandlerFactory</interfacename>
        interface. The <sgmltag class="starttag">parameters</sgmltag> subtag is
        optional and can be used to specify initialization parameters for the
        factory just as for action and renderer factories.
      </para>

      <programlisting language="xml">
<![CDATA[
<extensions
   xmlns="http://base.thep.lu.se/extensions.xsd"
   >
   <extension-point
      id="net.sf.basedb.clients.web.menu.extensions"
      >
      <action-class>net.sf.basedb.clients.web.extensions.menu.MenuItemAction</action-class>
      <name>Menu: extensions</name>
      <error-handler-factory>
         <factory-class>
            ... some factory class ...
         </factory-class>
         <parameters>
            ... initialization parameters ...
         </parameters>
      </error-handler-factory>
   </extension-point>
</extensions>
]]>
</programlisting>
    </sect2>
  </sect1>
  
  <sect1 id="extensions_developer.servlets">
    <?dbhtml filename="servlets.html" ?>
    <title>Custom servlets</title>
    <para>
      It is possible for an extension to include servlets without having
      to register those servlets in Tomcat's <filename>WEB-INF/web.xml</filename>
      file. The extension needs to be in a JAR file as usual. The servlet class
      should be located in the JAR file following regular Java conventions.
      Eg. The class <classname>my.domain.ServletClass</classname> should
      be located at <filename>my/domain/ServletClass.class</filename>. You 
      also need to create a second XML file that contains the servlet
      definitions at <filename>META-INF/servlets.xml</filename>. The format for
      defining servlets in this file is very similar to how servlets are
      defined in the <filename>web.xml</filename> file. Here is an example:
    </para>
    
    <programlisting language="xml">
<![CDATA[
<?xml version="1.0" encoding="UTF-8" ?>
<servlets xmlns="http://base.thep.lu.se/servlets.xsd">
   <servlet>
      <servlet-name>HelloWorld</servlet-name>
      <servlet-class>net.sf.basedb.examples.extensions.HelloWorldServlet</servlet-class>
      <init-param>
         <param-name>template</param-name>
         <param-value>Hello {user}! Welcome to the Servlet world!</param-value>
      </init-param>
   </servlet>
</servlets>
]]>
</programlisting>

    <para>
      The <sgmltag class="starttag">servlets</sgmltag> tag is the root tag and is 
      needed to set up the namespace and schema validation. This may contain
      any number of <sgmltag class="starttag">servlet</sgmltag> tags, each one
      defining a single servlet.
    </para>
    
    <para>
      The <sgmltag class="starttag">servlet-name</sgmltag> tag contains the name
      of the servlet. This is a required tag and must be unique among the servlets
      defined by this extension. Other extensions may use the same name without any
      problems.
    </para>
    
    <para>
      The <sgmltag class="starttag">servlet-class</sgmltag> tag contains the name
      of implementing class. This is required and the class must implement
      the <interfacename>Servlet</interfacename> interface and have a public,
      no-argument constructor. We recommend that servlet implementations instead 
      extends the <classname>HttpServlet</classname> class. This will make the 
      servlet programming easier.
    </para>
    
    <para>
      A servlet may have any number <sgmltag class="starttag">init-param</sgmltag>
      tags, containing initialisation parameters for the servlet. Here is the
      code for the servlet references in the above example.
    </para>

    <programlisting language="java">
<![CDATA[
public class HelloWorldServlet 
   extends HttpServlet 
{
   private String template;
   public HelloWorldServlet()
   {}

   @Override
   public void init()
      throws ServletException
   {
      ServletConfig cfg = getServletConfig();
      template = cfg.getInitParameter("template");
      if (template == null) template = "Hello {user}.";
   }

   @Override
   protected void doGet(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException
   {
      final SessionControl sc = Base.getExistingSessionControl(request, true);
      final DbControl dc = sc.newDbControl();
      try
      {
         User current = User.getById(dc, sc.getLoggedInUserId());
         PrintWriter out = response.getWriter();
         out.print(template.replace("{user}", current.getName()));
      }
      finally
      {
         if (dc != null) dc.close();
      }
   }
   @Override
   protected void doPost(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException
   {
      doGet(req, resp);
   }
}
]]>
</programlisting>

    <para>
      Invoking the servlet is done with a URL that is constructed like:
      <filename>$HOME$/[servlet-name].servlet</filename>, where <code>$HOME$</code>
      is the home directory of the extension. An alternate URL 
      that doesn't require the <filename>.servlet</filename> extension is available: 
      <filename>$SERVLET_HOME$/[servlet-name]</filename>, where <code>$SERVLET_HOME$</code>
      is the home directory of servlets for the extension. Note that this 
      directory is on a different sub-path than the <code>$HOME$</code> directory.
    </para>
    <para>
      Extra path information is supported 
      if it is inserted between the servlet name and the <filename>.servlet</filename>
      extension: <filename>$HOME$/[servlet-name][/extra/path/info].servlet</filename>,
      <filename>$SERVLET_HOME$/[servlet-name][/extra/path/info]</filename>
      
    </para>
    <para>
      Query parameters are supported as normal:
      <filename>$HOME$/[servlet-name].servlet?param1=value&amp;param2=value</filename>,
      <filename>$SERVLET_HOME$/[servlet-name]?param1=value&amp;param2=value</filename>
    </para>
    

    <programlisting language="xml">
<![CDATA[
<extension
   id="net.sf.basedb.clients.web.menu.extensions.helloservletworld"
   extends="net.sf.basedb.clients.web.menu.extensions"
   >
   <index>5</index>
   <about>
      <name>Hello Servlet world</name>
      <description>
         This example uses a custom Servlet page to display the
         "Hello world" message instead of a javascript popup.
      </description>
   </about>
   <action-factory>
      <factory-class>
         net.sf.basedb.clients.web.extensions.menu.FixedMenuItemFactory
      </factory-class>
      <parameters>
         <title>Hello Servlet world!</title>
         <tooltip>Opens a Servlet generated page with the message</tooltip>
         <data-url>$HOME$/HelloWorld.servlet?ID=$SESSION-ID$</data-url>
         <data-popup>HelloServletWorld, 400, 300</data-popup>
         <icon>~/images/servlet.png</icon>
      </parameters>
   </action-factory>
</extension>
]]>
</programlisting>
    
    <note>
      <para>
        To keep things as simple as possible, a new instance of the servlet 
        class is created for each request. If the servlet needs complex or 
        expensive initialisation, that should be externalised to other
        classes that the servlet can use.
      </para>
    </note>
    
  </sect1>
  
  <sect1 id="extensions_developer.base_extension_points">
    <?dbhtml filename="builtin.html" ?>
    <title>Extension points defined by BASE</title>
    
    <para>
      In this section, we will give an overview of the extension points defined
      by BASE. Most extension points are used in the web client to add
      buttons and menu items, but there are a few for the core API as well.
    </para>
    
    <sect2 id="extensions_developer.menuitems">
      <title>Menu: extensions</title>
      
      <para>
        Menu items can be added to the top-level 
        <menuchoice><guimenu>Extensions</guimenu></menuchoice>
        menu. Actions should implement the interface: <interfacename 
        docapi="net.sf.basedb.clients.web.extensions.menu">MenuItemAction</interfacename>
      </para>
      
      <para>
        The <methodname>MenuItemAction.getMenuType()</methodname> provides support
        for <constant>MENUITEM</constant>, <constant>SUBMENU</constant> and
        <constant>SEPARATOR</constant> menus. Which of the other properties that
        are needed depend on the menu type. Read the javadoc for more information.
        The rendering is internal (eg. extensions can't provide their own renderers).
      </para>
      
      <para>
        BASE ships with two action factories: 
        <classname docapi="net.sf.basedb.clients.web.extensions.menu">FixedMenuItemFactory</classname> and
        <classname docapi="net.sf.basedb.clients.web.extensions.menu">PermissionMenuItemFactory</classname>.
        
        The fixed factory provides a menu that is the same for all users.
        The permission factory can disable or hide a menu depending on the
        logged in user's role-based permissions. The title, icon, etc. can have
        different values depending on if the menu item is disabled or enabled.
      </para>
      
      <note>
        <title>onclick has been removed</title>
        <para>
          The onclick attribute has been deprecated since BASE 3.3 and was removed in BASE 3.5. Use a custom script instead to
          bind the click event with the menu item or <sgmltag class="starttag">data-url</sgmltag>
          if the menu simply navigates to another page. <sgmltag class="starttag">data-popup</sgmltag> 
          can be used to open the page in a popup window and should contain three comma-separated
          values: name-of-window, width-of-window, height-of-window
        </para>
      </note>
    </sect2>
    
    <sect2 id="extensions_developer.toolbars">
      <title>Toolbars</title>
      <para>
        Most toolbars on all list and single-item view pages can
        be extended with extra buttons. Actions should implement
        the interface: <interfacename 
          docapi="net.sf.basedb.clients.web.extensions.toolbar">ButtonAction</interfacename>.
        Button actions are very simple and only need to provide things like
        a title, tooltip, icon, etc. This extension point has
        support for custom javascript, stylesheets and renderers. The
        default renderer is <classname 
        docapi="net.sf.basedb.clients.web.extensions.toolbar">ToolbarButtonRendererFactory</classname>.
      </para>

      <para>
        BASE ships with two action factories: 
        <classname docapi="net.sf.basedb.clients.web.extensions.toolbar">FixedButtonFactory</classname> and
        <classname docapi="net.sf.basedb.clients.web.extensions.toolbar">PermissionButtonFactory</classname>.
        
        The fixed factory provides a toolbar button that is the same for all users.
        The permission factory can disable or hide a buton depending on the
        logged in user's role-based permissions. The title, icon, etc. can have
        different values depending on if the menu item is disabled or enabled.
      </para>
      
      <note>
        <title>onclick has been removed</title>
        <para>
          The onclick attribute has been deprecated since BASE 3.3 and was removed in BASE 3.5. Use a custom script instead to
          bind the click event with the button. Download the example code to see it in action.
        </para>
      </note>
      
    </sect2>

    <sect2 id="extensions_developer.edit_dialogs">
      <title>Edit dialogs</title>
      
      <para>
        Most item edit dialogs can be extended with additional tabs. 
        Actions should implement the interface: <interfacename 
          docapi="net.sf.basedb.clients.web.extensions.tabcontrol">TabAction</interfacename>.
        The actions are, in principle, simple and only need to
        provide a title and content (HTML). The action may also provide 
        javascripts for validation, etc. This extension point has support
        for custom stylesheets and javascript. Rendering is fixed and can't
        be overridden.
      </para>
      
      <para>
        BASE ships with two action factories: 
        <classname docapi="net.sf.basedb.clients.web.extensions.tabcontrol">FixedTabFactory</classname> and
        <classname docapi="net.sf.basedb.clients.web.extensions.tabcontrol">IncludeContentTabFactory</classname>.
        
        The fixed factory provides a tab with fixed content that is the same for all users
        and all items. This factory is not very useful in a real scenario.
        The other factory provides content by including the output from another resource,
        eg. a JSP page, a servlet, etc. The current context is stored in a request-scoped
        attribute under the key given by <code>JspContext.ATTRIBUTE_KEY</code>. 
        A JSP or servlet should use this to hook into the current flow. Here is a code example:
      </para>
      
      <programlisting language="java">
<![CDATA[
// Get the JspContext that was created on the main edit page
final JspContext jspContext = (JspContext)request.getAttribute(JspContext.ATTRIBUTE_KEY);

// The current item is found in the context. NOTE! Can be null if a new item
final BasicItem item = (BasicItem)jspContext.getCurrentItem();

// Get the DbControl and SessionControl used to handle the request (do not close!)
final DbControl dc = jspContext.getDbControl();
final SessionControl sc = dc.getSessionControl();
]]>
</programlisting>

      <para>
        The extra tab need to be paired with an extension that is invoked when
        the edit form is saved. Each edit-dialog extension point has a corresponding
        on-save extension point. Actions should implement the interface: <interfacename 
          docapi="net.sf.basedb.clients.web.extensions.edit">OnSaveAction</interfacename>.
        
        This interface define three callback methods that BASE will call when
        saving an item. The <methodname>OnSaveAction.onSave()</methodname>
        method is called first, but not until all regular properties have been
        updated. If the transaction is committed the <methodname>OnSaveAction.onCommit()</methodname>
        method is also called, otherwise the <methodname>OnSaveAction.onRollback()</methodname>
        is called. The <methodname>onSave()</methodname> method can throw an exception that
        will be displayed to the user. The other callback method should not throw exceptions
        at all, since that may result in undefined behaviour and can be confusing for the user.
      </para>
    </sect2>
    
    <sect2 id="extensions_developer.bioassayset_tools">
      <title>Bioassay set: Tools</title>
      <para>
        The bioassay set listing for an experiment has a <guilabel>Tools</guilabel>
        column which can be extended by extensions. This extension point is similar
        to the toolbar extension points and actions should implement
        the interface: <interfacename 
          docapi="net.sf.basedb.clients.web.extensions.toolbar">ButtonAction</interfacename>.
      </para>
      
      <para>
        Note that the list can contain 
        <classname docapi="net.sf.basedb.core">BioAssaySet</classname>,
        <classname docapi="net.sf.basedb.core">Transformation</classname> and
        <classname docapi="net.sf.basedb.core">ExtraValue</classname> items.
        The factory implementation need to be aware of this if it uses
        the <methodname>JspContext.getItem()</methodname> method to examine the
        current item.
      </para>
    </sect2>

    <sect2 id="extensions_developer.bioassayset_plots">
      <title>Bioassay set: Overview plots</title>
      <para>
        The bioassay set page has a tab <guilabel>Overview plots</guilabel>.
        The contents of this tab is supposed to be some kind of images
        that have been generated from the data in the current bioassay set.
        What kind of plots that can be generated typically depends on the
        kind of data you have. BASE ships with an extension 
        (<classname docapi="net.sf.basedb.clients.web.extensions">MAPlotFactory</classname>)
        that creates MA plots and Correction factor plots for 2-channel bioassays.
        Actions should implement the interface: 
        <interfacename docapi="net.sf.basedb.clients.web.extensions.plot">OverviewPlotAction</interfacename>.
        A single action generates a sub-tab in the <guilabel>Overview plots</guilabel> tab.
        The sub-tab may contain one or more images. Each image is defined by a
        <interfacename docapi="net.sf.basedb.clients.web.extensions.plot">PlotGenerator</interfacename>
        which sets the size of the image and provides an URL to a servlet that generates 
        the actual image. It is recommended that the servlet cache images since the
        data in a bioassay set never changes. The BASE core API provides a
        system-managed file cache that is suitable for this. Call 
        <methodname>Application.getStaticCache()</methodname> to get a 
        <classname docapi="net.sf.basedb.util">StaticCache</classname> instance.
        See the source code for the core 
        <classname docapi="net.sf.basedb.clients.web.servlet">PlotServlet</classname>
        for details of how to use the cache.
      </para>
      
    </sect2>

    <sect2 id="extensions_developer.services">
      <title>Services</title>
      <para>
        A service is a piece of code that is loaded when the BASE web 
        server starts up. The service is then running as long as the BASE web 
        server is running. It is possible to manually stop and start services. 
        This extension point is different from most others in that it doesn't 
        affects the visible interface. Since services are loaded at startup time, 
        this also means that the context passed to <interfacename>ActionFactory</interfacename> 
        methods will have a special <classname>ClientContext</classname> associated with it.
        There is no current item, and no user is logged in. However, the <classname>SessionControl</classname>
        returned from <methodname>ClientContext.getSessionControl()</methodname> gives
        permission to imporsonate another making it possible for the extension
        to access the BASE database almost without limitation. There is no meaning for 
        extensions to specify a <interfacename>RendererFactory</interfacename>. Service 
        actions should implement the interface: 
        <interfacename docapi="net.sf.basedb.clients.web.extensions.service">ServiceControllerAction</interfacename>.
        
        The interface provides <methodname>start()</methodname> and
        <methodname>stop()</methodname> methods for controlling the service.
        BASE doesn't ship with any service, but there is an FTP service 
        available at the BASE plug-ins site: <ulink 
        url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.ftp">
        http://baseplugins.thep.lu.se/wiki/net.sf.basedb.ftp</ulink>
      </para>
    </sect2>

    <sect2 id="extensions_developer.service-actions">
      <title>Service actions</title>
      <para>
        The services list page has an <guilabel>Action</guilabel> column
        for showing the <guilabel>Start</guilabel> and <guilabel>Stop</guilabel>
        actions as well as any other actions extending this extension point.
        This extension point is similar to the toolbar extension points and actions
        should implement the <interfacename 
          docapi="net.sf.basedb.clients.web.extensions.toolbar">ButtonAction</interfacename>
        interface. This extension point supports custom scripts and stylesheets. 
        
        Note that all extensions are invoked for all services. The 
        <methodname>ClientContext.getItem()</methodname> returns the 
        <interfacename docapi="net.sf.basedb.clients.web.extensions.service">ServiceControllerAction</interfacename>
        instance for the current service. Extensions should use this to
        decide if an action should be created or not.
      </para>
    </sect2>

    <sect2 id="extensions_developer.connection_manager">
      <title>Connection managers</title>
      <para>
        This extension point adds support for using external files
        in BASE. This is a core extension point and is available
        independently of the web client. Actions should implement
        the interface: 
        <interfacename docapi="net.sf.basedb.util.uri">ConnectionManagerFactory</interfacename>.
      </para>
      
      <para>
        The <methodname>getDisplayName()</methodname> and <methodname>getDescription()</methodname>
        methods are used in the gui when a user manually selects which connection
        manager to use. The <methodname>supports(URI)</methodname> is used when auto-selecting
        a connection manager based on the URI of the resource.
      </para>
      
      <para>
        BASE ships with factory that supports HTTP and HTTPS file
        references: <classname 
        docapi="net.sf.basedb.util.uri.http">HttpConnectionManagerFactory</classname>.
        
        The BASE plug-ins site has an connection manager that support
        external files via FTP and SFTP: <ulink 
        url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.xfiles">
        http://baseplugins.thep.lu.se/wiki/net.sf.basedb.xfiles</ulink>
      </para>
      
    </sect2>

    <sect2 id="extensions_developer.fileset_validator">
      <title>Fileset validators</title>
      
      <itemizedlist>
        <title>See also</title>
        <listitem><para><xref linkend="core_api.data_in_files" /></para></listitem>
        <listitem><para><xref linkend="data_api.platforms" /></para></listitem>
      </itemizedlist>
  
      <para>
        In those cases where files are used to store data instead
        of importing it to the database, BASE can use extensions to 
        check that the supplied files are valid and also to extract
        metadata from the files. For example, the 
        <classname docapi="net.sf.basedb.util.affymetrix">CelValidationAction</classname>
        is used to check if a file is a valid Affymetrix CEL file and
        to extract data headers and the number of spots from it.
      </para>
      
      <para>
        Validation and metadata extraction actions should implement
        the <interfacename docapi="net.sf.basedb.util.fileset">ValidationAction</interfacename>
        interface. This is a core extension point and is available
        independently of the web client.
      </para>
      
      <para>
        This extension point is a bit more complex than most other extension
        points. To begin with, the factory class will be called with the
        owner of the file set as the current item. Eg. the 
        <code>ClientContext.getCurrentItem()</code> should return a
        <interfacename docapi="net.sf.basedb.core">FileStoreEnabled</interfacename>
        item. It is recommended that the factory performs a pre-filtering
        of the items to avoid calling the actual validation code on unsupported
        files. For example, the <classname docapi="net.sf.basedb.util.affymetrix">CelValidationFactory</classname>
        will check that the item is a <classname docapi="net.sf.basedb.core">RawBioAssay</classname>
        item using the Affymetrix platform.
      </para>
      
      <para>
        Each file in the file set is then passed to the
        <methodname>ValidationAction.acceptFile(FileSetMember)</methodname>
        which may accept or reject the file. If the file is accepted it may
        be accepted for immediate validation or later validation. The latter option
        is useful in more complex scenarios were files need to be validated as a group.
        If the file is accepted the <methodname>ValidationAction.validateAndExtractMetadata()</methodname>
        is called, which is were the real work should happen.
      </para>
      
      <para>
        The extensions for this extension point is also called when a file is replaced
        or removed from the file set. The calling sequence to set up the validation is
        more or less the same as described above, but the last step is to 
        call <methodname>ValidationAction.resetMetadata()</methodname> instead
        of <methodname>ValidationAction.validateAndExtractMetadata()</methodname>.
      </para>

      <tip>
        <title>
          Use the <classname docapi="net.sf.basedb.util.fileset">SingleFileValidationAction</classname>
          class.
        </title>
        <para>
          Most validators that work on a single file at a time may find the
          <classname>SingleFileValidationAction</classname> class useful. Is should
          simplify the task of making sure that only the desired file type is
          validated. See the source code of the <classname 
          docapi="net.sf.basedb.util.affymetrix">CelValidationAction</classname>
          class for an example.
        </para>
      </tip>
      
    </sect2>
  
    <sect2 id="extensions_developer.logging">
      <title>Logging managers</title>
      
      <para>
        This extension point makes it possible to detect changes that are made to
        item and generate log entries in real time. The core will send notifications
        for all item creations, updates and deletions to all registered logging
        managers. It is up to each implementation to decide if an event should be
        logged, where to log it and how much information that should be stored. 
        The BASE core provides a logging implementation that save some information
        to the database which can also be viewed through the web interface.
      </para>
      
      <para>
        The logging mechanism works on the data layer level and hooks into
        callbacks provided by Hibernate. <interfacename 
        docapi="net.sf.basedb.core.log">EntityLogger</interfacename>:s are used to
        extract relevant information from Hibernate and create log entries.
        While it is possible to have a generic logger it is usually better
        to have different implementations depending on the type of entity that
        was changed. For example, a change in a child item should, for usability
        reasons, be logged as a change in the parent item. Entity loggers
        are created by a <interfacename 
        docapi="net.sf.basedb.core.log">LogManagerFactory</interfacename>. All changes
        made in a single transaction are usually collected by a <interfacename 
        docapi="net.sf.basedb.core.log">LogManager</interfacename> which is also
        created by the factory.
      </para>
      
      <sect3 id="extensions_developer.logging.factory">
        <title>The LogManagerFactory interface</title>
        
        <para>
          Each registered action factory shoulds create a <interfacename 
          docapi="net.sf.basedb.core.log">LogManagerFactory</interfacename> 
          that is used throughout a single transaction. If the factory is
          thread-safe, the same instance can be re-used for multiple requests
          at the same time. Here is a list of
          the methods the factory must implement:
        </para>
        
        <variablelist>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>LogManager</type>
                <methodname>getLogManager</methodname>
                <methodparam>
                  <type>LogControl</type>
                  <parameter>logControl</parameter>
                </methodparam>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
              Creates a log manager for a single transaction. Since a transaction
              is not thread-safe the log manager implementation doesn't have to
              be either. The factory has the possibility to create new log managers
              for each transaction.
              </para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>boolean</type>
                <methodname>isLoggable</methodname>
                <methodparam>
                  <type>Object</type>
                  <parameter>entity</parameter>
                </methodparam>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
              Checks if changes to the given entity should be
              logged or not. For performance reasons, it usually makes sense to 
              not log everything. For example, the database logger implementation 
              only logs changes if the entity implements the <interfacename 
              docapi="net.sf.basedb.core.data">LoggableData</interfacename>
              interface. The return value of this method should be consistent
              with <methodname>getEntityLogger()</methodname>.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>EntityLogger</type>
                <methodname>getEntityLogger</methodname>
                <methodparam>
                  <type>LogManager</type>
                  <parameter>logManager</parameter>
                </methodparam>
                <methodparam>
                  <type>Object</type>
                  <parameter>entity</parameter>
                </methodparam>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
              Create or get an entity logger that knows how to log
              changes to the given entity. If the entity should not be
              logged, <constant>null</constant> can be returned. This method
              is called for each modified item in the transaction.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        
      </sect3>
      
      <sect3 id="extensions_developer.logging.manager">
        <title>The LogManager interface</title>
        
        <para>
          A new log manager is created for each transaction. The log manager
          is responsible for collecting all changes made in the transaction 
          and store those changes in the appropriate place. The interface doesn't define
          any methods for this collection, since each implementation may have
          very different needs.
        </para>
        
        <variablelist>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <type>LogControl</type>
                <methodname>getLogControl</methodname>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
              Get the log control object that was supplied by the BASE core
              when the transaction was started. The log controller contains
              methods for accessing information about the transaction, such
              as the logged in user, executing plug-in, etc. It can also
              be used to execute queries against the database to get
              even more information.
              </para>
              
              <warning>
                <para>
                  Be careful about the queries that are executed by the log
                  controller. Since all logging code is executed at flush
                  time in callbacks from Hibernate we are not allowed to
                  use the regular session. Instead, all queries are sent
                  through the stateless session. The stateless session has no
                  caching functionality which means that Hibernate will use
                  extra queries to load associations. Our recommendation is
                  to avoid quires that return full entities, use scalar 
                  queries instead to just load the values that are needed.
                </para>
              </warning>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <void/>
                <methodname>afterCommit</methodname>
              </methodsynopsis>
            </term>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <void/>
                <methodname>afterRollback</methodname>
              </methodsynopsis>
            </term>
            <listitem>
              Called after a successful commit or after a rollback. Note
              that the connection to the database has been closed at this
              time and it is not possible to save any more information to 
              it at this time.
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>

      <sect3 id="extensions_developer.logging.entitylogger">
        <title>The EntityLogger interface</title>
        
        <para>
          An entity logger is responsible for extracting the changes 
          made to an entity and converting it to something that is useful
          as a log entry. In most cases, this is not very complicated, but
          in some cases, a change in one entity should actually be logged
          as a change in a different entity. For example, changes to
          annotations are handled by the <classname 
          docapi="net.sf.basedb.core.log.db">AnnotationLogger</classname> which
          which log it as a change on the parent item.
        </para>
        
        <variablelist>
          <varlistentry>
            <term>
              <methodsynopsis language="java">
                <modifier>public</modifier>
                <void/>
                <methodname>logChanges</methodname>
                <methodparam>
                  <type>LogManager</type>
                  <parameter>logManager</parameter>
                </methodparam>
                <methodparam>
                  <type>EntityDetails</type>
                  <parameter>details</parameter>
                </methodparam>
              </methodsynopsis>
            </term>
            <listitem>
              <para>
              This method is called whenever a change has been detected
              in an entity. The <varname>details</varname> variable contains
              information about the entity and, to a certain degree, 
              what changes that has been made.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect3>
      
    </sect2>
  
  
    <sect2 id="extensions_developer.overview_loader">
      <title>Item overview loaders</title>
      
      <para>
        The item overview functionality allow extensions to load more items in the tree
        structure. The extension point is a core extension point that is available 
        independently of the web client. Actions should implement the 
        <interfacename docapi="net.sf.basedb.util.overview.extensions">ChildNodeLoaderAction</interfacename>
        interface. We recommend that the actions also extend the 
        <classname docapi="net.sf.basedb.util.overview.loader">BasicItemNodeLoader</classname>
        since this will make it easier to handle situations with missing items, permission
        problems and validation. Since each registered extension is checked for each item
        in the overview we recommend that the action factory makes a first filtering step
        before an action is created. This should be relatively simple since the current
        item in the <classname>ClientContext</classname> is the parent node. For example:
      </para>
      
      <programlisting language="java">
<![CDATA[
// From the ActionFactory interface
public boolean prepareContext(InvokationContext<? super ChildNodeLoaderAction> context) 
{
   Node parentNode = (Node)context.getClientContext().getCurrentItem();
   if (parentNode != null)
   {
      if (parentNode.getItem() instanceof Ownable)
      {
         return true;
      }
   }
   return false;
}
]]>
</programlisting>
      
    </sect2>
    
    <sect2 id="extensions_developer.overview_validator">
      <title>Item overview validation</title>
      
      <para>
        The item overview functionality allow extensions to add validation code
        to any item in the tree. There are two co-existing extension points, one
        for the actual validation code and one for the validation rule defintions.
        Both extension points are core extension points that is available 
        independently of the web client. Validation actions should implement the 
        <interfacename docapi="net.sf.basedb.util.overview.extensions">NodeValidatorAction</interfacename>
        interface, which is simple the same as <interfacename docapi="net.sf.basedb.util.overview.validator">NodeValidator</interfacename>
        We recommend that the actions extend the 
        <classname docapi="net.sf.basedb.util.overview.validator">NameableNodeValidator</classname>
        or <classname docapi="net.sf.basedb.util.overview.validator">BasicNodeValidator</classname>
        since this will make it easier to handle situations with missing items and permission
        problems. Since each registered extension is checked for each item
        in the overview we recommend that the action factory makes a first filtering step
        before an action is created. This should be relatively simple since the current
        item in the <classname>ClientContext</classname> is type of that should be validated.
        For example:
      </para>
      
      <programlisting language="java">
<![CDATA[
// From the ActionFactory interface
public boolean prepareContext(InvokationContext<? super NodeValidatorAction> context) 
{
   return context.getClientContext().getCurrentItem() == Item.USER;
}
]]>
</programlisting>

      <para>
        Rule definition actions should implement the <interfacename 
        docapi="net.sf.basedb.util.overview.extensions">ValidationRuleAction</interfacename>. 
        This is simply a container with some information about the validation rule, such as
        a title, description and a default severity level. The 
        <classname docapi="net.sf.basedb.util.overview">Validator</classname> class
        that ships with BASE already implements this interface. The <classname 
        docapi="net.sf.basedb.util.overview.extensions">ReflectValidationRuleActionFactory</classname>
        can be used to return an existing <code>public static final</code> rule definition as an 
        action:
      </para>
      
      <programlisting language="xml">
<![CDATA[
<extension
   id="validationrule.invalid-url"
   extends="net.sf.basedb.util.overview.validationrule">
   <index>4</index>
   <about>
      <name>Invalid URL</name>
      <description>Checks if an URL has a valid syntax.</description>
   </about>
   <action-factory>
      <factory-class>
         net.sf.basedb.util.overview.extensions.ReflectValidationRuleActionFactory
      </factory-class>
      <parameters>
         <field>net.sf.basedb.examples.extensions.overview.OwnerValidator.INVALID_URL</field>
      </parameters>
   </action-factory>
</extension>
]]>
</programlisting>
      
    </sect2>
    
    <sect2 id="extensions_developer.overview_information">
      <title>Item overview information</title>
      
      <para>
        The item overview functionality allow extensions to display additional information
        about the currently selected node in the right pane in the web interface. 
        Each <interfacename docapi="net.sf.basedb.clients.web.extensions.section">SectionAction</interfacename> 
        object that is created by extensions will result in an additional section in the
        GUI. Note that all extension factories are called for all nodes. The
        <methodname>ActionFactory.prepareContext()</methodname> should be used to enable/disable
        the extension depending on the node that is selected. BASE ships with the
        <classname docapi="net.sf.basedb.clients.web.extensions.section">IncludeContentSectionFactory</classname>
        factory implementation which allows a resourse (eg. another JSP script) to generate
        the content of the section. The current context is stored in a request-scoped
        attribute under the key given by <code>JspContext.ATTRIBUTE_KEY</code>. 
        A JSP or servlet should use this to hook into the current flow. Here is a code example:
      </para>
      
      <programlisting language="java">
<![CDATA[
// Get the JspContext that was created on the main edit page
final JspContext jspContext = (JspContext)request.getAttribute(JspContext.ATTRIBUTE_KEY);

// The currently selected node is found in the context.
final Node node = (Node)jspContext.getCurrentItem();

// Get the DbControl and SessionControl used to handle the request (do not close!)
final DbControl dc = jspContext.getDbControl();
final SessionControl sc = dc.getSessionControl();
]]>
</programlisting>
        
    </sect2>
    
    
    <sect2 id="extensions_developer.list_column">
      <title>Table list columns</title>
      
      <para>
        This extension point makes it possible to add more columns to most major list pages
        in the web interface. Actions should implement the <interfacename 
        docapi="net.sf.basedb.clients.web.extensions.list">ListColumnAction</interfacename> interface.
        This interface contains several methods which can be grouped into three main types:
      </para>

      <itemizedlist>
        <listitem>
          <para>
            Metadata methods, for example, the id and title of the column and if the column
            can be sorted, filtered, etc.
          </para>
        </listitem>
        
        <listitem>
          <para>
            Rendering information, for example, CSS class and style information that is 
            used for the column header.
          </para>
        </listitem>
        
        <listitem>
          <para>
            Worker methods, that retrieve the value from the current item and format
            it for proper display. Different methods are used for the web display
            and for exporting to a file.
          </para>
        </listitem>
      </itemizedlist>
      
      <para>
        The <classname docapi="net.sf.basedb.clients.web.extensions.list">AbstractListColumnBean</classname>
        class provides a bean-like implementation for all methods except the <methodname>getValue()</methodname>
        method. Extending from this class makes it easy to your own implementations. BASE ships with the
        <classname docapi="net.sf.basedb.clients.web.extensions.list">PropertyPathActionFactory</classname>
        factory that can be used without coding if the added column can be expressed as a property path that
        can be handled by the <classname docapi="net.sf.basedb.core">Metadata</classname> class.
        As usual, see the <ulink url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.examplecode">example code</ulink> 
        for some examples.
      </para>
      
    </sect2>
    
    <sect2 id="extensions_developer.login-manager">
      <title>Login manager</title>
      <para>
        This extension point makes it possible to authenticate users by some other means than
        the regular internal username+password authentication. Authentication managers should
        implement the <classname docapi="net.sf.basedb.core.authentication">AuthenticationManager</classname>
        action interface. This interface is simple and the only method that is required to implement
        is the parameter-less <methodname>authenticate()</methodname> method. There are three outcomes:
      </para>
      
      <itemizedlist>
        <listitem>
          <para>A <classname docapi="net.sf.basedb.core.authentication">AuthenticatedUser</classname>
          is returned with information about a user that has passed authentication.
          </para>
        </listitem>
        
        <listitem>
          <para>A <constant>null</constant> value is returned to indicate that the manager could
          not determine if the login credentials are valid or not. The BASE core may try another
          authentication manager or use internal authentication.
          </para>
        </listitem>
        
        <listitem>
          <para>An exception is thrown to indicate that the manager has determined that
          the login credentials are invalid.
          </para>
        </listitem>
        
      </itemizedlist>
      
      <para>
        Since the action interface doesn't contain any parameters that contain information about the 
        login request, the implementation need to get this from the <classname 
        docapi="net.sf.basedb.util.extensions">ClientContext</classname> that is passed to the 
        action factory. The <methodname>getCurrentItem()</methodname> item is a <classname 
        docapi="net.sf.basedb.core.authentication">LoginRequest</classname> containing the login and
        password the user entered on the login page. The <classname>ClientContext</classname>
        ojbect can be cast to <classname docapi="net.sf.basedb.core">AuthenticationContext</classname>
        which provide some extra services to the authentication manager.
      </para>
      
      <sect3 id="extensions_developer.login-manager.multiple">
        <title>Supporting multiple installed login managers</title>
        
        <para>
          As of BASE 3.14 it should be easier to support server configurations that
          include multiple login manages. The <code>login-form</code> attribute in the
          <classname>LoginRequest</classname> parameter contains the login form
          that was used by the user. A login manager should check this value 
          to decide if the login request should be handled or not. Note that 
          the value may be missing.
        </para>
        
        <para>
          The <classname docapi="net.sf.basedb.core.authentication">AuthenticationManager</classname>
          interface also includes an optional method, 
          <methodname>vetoAuthenticatedUser(UserData, AuthenticatedUser)</methodname>. This method
          is only called if one of the installed login manager authenticated the user successfully. 
          Then, all other installed login managers get a chance to raise a veto by throwing an
          exception from this method. A responsible login manager probably need to implement this
          method to detect if a user that is supposed to login with a specific method is trying to
          login with some other method. Examples of actual implementations can be found in the
          the <ulink 
          url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.yubikey">YubiKey</ulink>
          and <ulink 
          url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.otp">OTP</ulink> extensions.
        </para>
        
      </sect3>
      
      <sect3 id="extensions_developer.login-manager.internal-vs-external">
        <title>Internal vs. external authentation</title>
      
        <para>
          All login requests are always sent to registered authentication
          managers first. Internal authentication is only used if no authentication 
          manager could validate the user. Even with external authentication it is possible to 
          let BASE cache the logins/passwords. This makes it possible to login to 
          BASE if the external authentication server is down.
        </para>
        
        <note>
          <para>
          An external authentication server can only be used to grant or deny 
          a user access to BASE. It cannot be used to give a user permissions,
          or put a user into groups or different roles inside BASE.
          </para>
        </note>

        <para>
          The authentication process goes something like this:
          
          <itemizedlist>
          <listitem>
            <para>
              An external authentication manager determines that the login request
              is valid and the user is already known to BASE.
              If the extra information (name, email, phone, etc.) is supplied
              and the <property>auth.synchronize</property> setting
              is <constant>TRUE</constant> the extra information is copied to 
              the BASE server.
            </para>
          </listitem>
          
          <listitem>
            <para>
              An external authentication manager determines that the login request
              is valid, but the user is not known to BASE. This happens
              the first time a user logs in. BASE will create
              a new user account. If the authentication manager provides extra information, it 
              is copied to the BASE server (even if <property>auth.synchronize</property> 
              is not set). The new user account will get the default quota 
              and be added to the all roles and groups which has been
              marked as <emphasis>default</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              If password caching is enabled, the password is copied to BASE. 
              If an expiration timeout has been set, an expiration date
              will be calculated and set on the user account. The expiration
              date is only checked when the external authentication server is 
              down.
            </para>
          </listitem>

          <listitem>
            <para>
              The external authentication manager says that the login is invalid or 
              the password is incorrect. The user will not be logged in. 
            </para>
          </listitem>
          
          <listitem>
            <para>
              The authentication manager says that something else is wrong. 
              If password caching is enabled, internal authentication will be 
              used. Otherwise the user will not be logged in.
            </para>
          </listitem>
          </itemizedlist>
          
        </para>
      </sect3>
      
      <sect3 id="pextensions_developer.login-manager.settings">
        <title>Configuration settings</title>
      
        <para>
          The configuration settings for the authentication system are located 
          in the <filename>base.config</filename> file. 
          Here is an overview of the settings. For more information read 
          <xref linkend="appendix.base.config.authentication" />.
        </para>
        
        <variablelist>
        <varlistentry>
          <term><property>auth.synchronize</property></term>
          <listitem>
            <para>
            If extra user information is synchronized at login time or not. 
            This setting is ignored if the driver does not support extra information. 
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><property>auth.cachepasswords</property></term>
          <listitem>
            <para>
              If passwords should be cached by BASE or not. If the passwords are 
              cached a user may login to BASE even if the external authentication 
              server is down.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><property>auth.daystocache</property></term>
          <listitem>
            <para>
              How many days to cache the passwords if caching has been enabled. 
              A value of 0 caches the passwords for ever.     
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
      </sect3>
      
    </sect2>
    
    <sect2 id="extensions_developer.login-form">
      <title>Login form</title>
      
      <para>
        This extension point is typically used in combination with a login manager to provide a
        customized login form. Extensions should implement the <interfacename 
        docapi="net.sf.basedb.clients.web.extensions.login">LoginFormAction</interfacename>
        action which is used to specify prompts, tooltips, help texts and styling information
        for the login and password fields. The extension point supports custom scripts and stylesheets.
      </para>
      
      <note>
        <title>As of BASE 3.14 it is possible to install multiple login managers</title>
        <para>
          All installed and enabled login forms are available in a selection list
          from which the user can select to switch to another login form. For technical reasons 
          custom scripts and stylesheets are loaded for all installed login forms even
          though only one is displayed at a time. Developers must ensure that CSS rules
          and scripts are not affecting other login forms than the intended one.
        </para>
        <para>
          To help with this, BASE is setting two data-attributes on the 
          <sgmltag class="starttag">body</sgmltag> tag:
        </para>
        
        <variablelist>
        <varlistentry>
          <term><property>data-login-form</property></term>
          <listitem>
            <para>
            The ID of the currently active login form.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><property>data-requested-form</property></term>
          <listitem>
            <para>
            The ID of the login form that was requested. This may differ from the currently active
            if it is not installed or enabled.
            </para>
          </listitem>
        </varlistentry>
        </variablelist>
        
        <para>
          In CSS files, rules that are targeting elements on the login form should match
          against the <sgmltag class="attribute">data-login-form</sgmltag> attribute in the selector,
          for example:
        </para>
        
        <programlisting language="css">
/* Example from the YubiKey login form */
body[data-login-form="net.sf.basedb.yubikey.login-form"] 
   #loginform #login-row th
{
   background-image: url('../images/yubico.png');
   background-position: right center;
   background-repeat: no-repeat;
   padding-right: 20px;
}
</programlisting>
        
        <para>
          Scripts should also check the value of this attribute before doing stuff:
        </para>
        <programlisting language="javascript">
/* Examle from the OTP login form */
if (Data.get(document.body, 'login-form') != 'net.sf.basedb.otp.login-form') 
{
   // Not the OTP login form
   return;
}
</programlisting>

        <para>
          When logging in, the ID of the selected login form is added to the
          <classname docapi="net.sf.basedb.core.authentication">LoginRequest</classname>
          with attribute name <code>login-form</code> so that login managers can
          pick it up and take action on it.
        </para>

      </note>
      
    </sect2>
    
    <sect2 id="extensions_developer.skins">
      <title>Skins</title>
      
      <para>
        This extension point can be used to change the visual appearance of BASE. Contrary
        to other extension points, providing actions are optional. The skinning is
        done by having the action factory set style sheet and script files on the <classname 
        docapi="net.sf.basedb.clients.web.extensions">JspContext</classname> instance.
        Typically the style sheet override or set some properties defined by the BASE
        core stylesheets.
      </para>
      
      <para>
        Actions may be provided and should then implement the <interfacename 
        docapi="net.sf.basedb.clients.web.extensions.skin">SkinAction</interfacename>
        interface. Actions are needed if the skin extension wants to modify the
        fav-icon or include some data in a hidden <sgmltag class="starttag">div</sgmltag>
        tag. For this to work, the action must also implement the <interfacename 
        docapi="net.sf.basedb.clients.web.extensions">DynamicActionAttributes</interfacename>
        interface, since only the dynamic attribute values are included in the web page.
      </para>
      
      <para>
        BASE provides a simple action factory implementation,
        <classname docapi="net.sf.basedb.clients.web.extensions.skin">FixedSkinActionFactory</classname>,
        that supports all of the above.
      </para>
      
    </sect2>
    
    <sect2 id="extensions_developer.start-page">
      <title>Start page</title>
      
      <para>
        This extension point can be used to change the start page that is
        loaded after a use logs in to BASE. The normal start page is 
        the <menuchoice>
          <guimenu>BASE</guimenu>
          <guimenuitem>Home</guimenuitem>
        </menuchoice> page. Extensions should implement the <interfacename 
        docapi="net.sf.basedb.clients.web.extensions.startpage">StartPageAction</interfacename>
        interface. The current item in the <classname 
        docapi="net.sf.basedb.clients.web.extensions">JspContext</classname> 
        is the currently logged in user. All possible 
        start pages will be listed as a user configuration in the 
        <menuchoice>
          <guimenu>BASE</guimenu>
          <guimenuitem>Preferences</guimenuitem>
        </menuchoice> dialog. The ID of the selected start page is stored as
        a user setting. When the user is logging in to BASE the extension is
        queried for the URL to load and the browser is redirected to that page.
      </para>
      
      <para>
        BASE provides a simple action factory implementation:
        <classname docapi="net.sf.basedb.clients.web.extensions.startpage">FixedStartPageFactory</classname>.
      </para>
      
    </sect2>
  </sect1>
  
</chapter>