<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//MAKUMBA//DTD Documentation V2.0//EN" "document-v20-mak.dtd">
<document>
    <header>
        <title>Makumba configuration</title>
    </header>
    <body>
        <section>
            <title>Introduction</title>
            <p> Most of the Makumba configuration is centralised in the <code>WEB-INF/classes/Makumba.conf</code>
                file. This file is organised in sections, in an INI stlye, so as to be easier to
                read. </p>
        </section>
        <section>
            <title>Database configuration</title>
            <p>Makumba can retrieve data from one or more databases, yet its most common usage is
                to work with one database. Makumba has two database base layers, one native layer
                and one layer that uses Hibernate as an abstraction layer. The native Makumba layer
                supports several database engines, but in the past years has mostly been tested with
                MySQL. The Hibernate database layer uses Hibernate, hence supports many different
                database engines.</p>

            <section>
                <title>Global DataSource configuration [dataSourceConfig]</title>

                <table>
                    <tr>
                        <th>Parameter</th>
                        <th>Mandatory</th>
                        <th>Database Layer</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td>foreignKeys=true|false</td>
                        <td>no. true by default</td>
                        <td>Makumba</td>
                        <td>Whether foreign keys should be generated</td>
                    </tr>
                    <tr>
                        <td>defaultDataSource=value</td>
                        <td>yes</td>
                        <td>both</td>
                        <td>The name of the dataSource to be used by default</td>
                    </tr>
                </table>

            </section>

            <section id="datasource_configuration">
                <title>Data Sources [dataSource:name]</title>
                <p> A dataSource section provides the necessary information to establish a
                    connection with a database server. It is possible to configure several
                    dataSources and to use them at runtime. 
                <br/>
                    The syntax of a dataSource section is as
                    follows: <code>[dataSource:name host:hostname path:server path]</code>.
                <br/>
                    The
                    host and path elements are optional, and can be used to automatically use one
                    specific dataSource depending on which server the web-app runs on.
                </p>
                <p>
                    Example: the
                    dataSource <code> [dataSource:production host:production.mycompany.com
                        path:/opt/tomcat-production] </code> would be automatically selected
                    as default data source when the web-app is ran on production.mycompany.com and
                    the working directory of tomcat is /opt/tomcat-production, whereas
                    <code>[dataSource:test host:production.mycompany.com path:/opt/tomcat-test]</code> would be selected when the web-app is run from the tomcat running at
                    /opt/tomcat-test </p>
                <table>
                    <tr>
                        <th>Parameter</th>
                        <th>Mandatory</th>
                        <th>Database Layer</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td>databaseLayer=makumba|hibernate</td>
                        <td>yes</td>
                        <td>both</td>
                        <td>Which database layer should be used</td>
                    </tr>
                    <tr>
                        <td>connection.url=value</td>
                        <td>yes for the hibernate database layer</td>
                        <td>both</td>
                        <td>a JDBC URL to which to connect</td>
                    </tr>
                    <tr>
                        <td>connection.username=value</td>
                        <td>no</td>
                        <td>both</td>
                        <td>A username to connect to the dataSource</td>
                    </tr>
                    <tr>
                        <td>connection.password=value</td>
                        <td>no</td>
                        <td>both</td>
                        <td>A password to connect to the dataSource</td>
                    </tr>
                    <tr>
                        <td>connection.host=hostName</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>the host to which to connect</td>
                    </tr>
                    <tr>
                        <td>connection.port=portNumber</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>the port to which to connect</td>
                    </tr>
                    <tr>
                        <td>connection.database=databaseName</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>the name of the database to which to connect</td>
                    </tr>
                    <tr>
                        <td>connection.engine=engineName</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>the SQL engine to use</td>
                    </tr>
                    <tr>
                        <td>sql.setting=valuetd></td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>sends a setting to the JDBC driver (for example user, password, create,
                            etc). Such settings are JDBC driver specific</td>
                    </tr>
                    <tr>
                        <td>dbsv=value</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>the DBSV will be used to set the most significant 8 bits of all primary
                            keys generated for the new records created by this makumba client. Using
                            different DBSVs can help to ensure key uniqueness among multiple clients
                            using (or synchronizing with) the same database. Database inserts of
                            records that have the same primary key as an already existing record in
                            that table (i.e. a record created by a client that used the same DBSV)
                            will fail. You cannot specify both dbsv and auto_increment in the same
                            configuration file, but you can access the same database with some
                            clients using (different) dbsv-s, and others using autoIncrement.</td>
                    </tr>
                    <tr>
                        <td>autoIncrement=true|false</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>if autoIncrement is on, makumba will use the server-side primary key
                            generation. You cannot specify both dbsv and auto_increment in the same
                            configuration file, but you can access the same database with some
                            clients using (different) dbsv-s, and others using autoIncrement.</td>
                    </tr>
                    <tr>
                        <td>initConnections=value</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>specifies the initial number of connections that makumba will open when
                            connecting to the database. Default is 1, though some makumba versions
                            will open 2-3 more connections pretty early in their activity. High
                            server load will lead to more connections being open.</td>
                    </tr>
                    <tr>
                        <td>database_class=className</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>The main class of the makumba database driver. This is normally read
                            from org/makumba/db/sql/sqlEngines.properties, but other, more powerful
                            drivers can be plugged in.</td>
                    </tr>
                    <tr>
                        <td>table_class=className</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>Table handler of the database driver (optional, norlally known by the
                            dbclass or read from
                            org/makumba/db/makumba/db/sql/sqlEngines.properties)</td>
                    </tr>
                    <tr>
                        <td>typename=SQLtableName</td>
                        <td>no</td>
                        <td>both</td>
                        <td>Sets the name of the SQL table representing the given type to
                            SQLtableName (to inhibit automatic table name generation)</td>
                    </tr>
                    <tr>
                        <td>typename->field=SQLfieldName</td>
                        <td>no</td>
                        <td>both</td>
                        <td>Sets the name of the SQL field representing the given object attribute
                            to SQLfieldName (to inhibit automatic field name generation)</td>
                    </tr>
                    <tr>
                        <td>addUnderscore=true|false</td>
                        <td>no</td>
                        <td>both</td>
                        <td>Specifies whether to add an underscore at the end of the generated field
                            and table names during automatic name generation. It is true by default.
                            (Introduced to avoid conflicts with reserved words on some SQL
                            engines)</td>
                    </tr>
                    <tr>
                        <td>alter#typenameShorthand=true|false</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>If true allows automatic alteration of the SQL table representing the
                            type(s) when the SQL table doesn't match the type definition. For example:<br/>
                            <code>alter#=true</code><br/>
                            <code>alter#general=false</code><br/> will allow alteration of all
                            tables from the database except for tables whose names begin with
                            "general"</td>
                    </tr>
                    <tr>
                        <td>admin#typenameShorthand=true|false</td>
                        <td>no</td>
                        <td>Makumba</td>
                        <td>If true allows deletion of multiple records of the respective
                            types during org.makumba.delete and org.makumba.copy the type(s) when the
                            SQL table doesn't match the type definition.</td>
                    </tr>
                    
                    <tr>
                        <td>hibernate.dialect=className</td>
                        <td>yes</td>
                        <td>Hibernate</td>
                        <td>the dialect to use with the database server</td>
                    </tr>
                    <tr>
                        <td>makumba.seed=fileName</td>
                        <td>no</td>
                        <td>Hibernate</td>
                        <td>the file name of a file in the classpath, that will be used to determine
                            the root directory of the mappings and classes generated by Makumba in
                            order to use Hibernate as a database layer. by default it is
                            Makumba.conf, hence the classes and mappings will be generated under
                            WEB-INF/classes.</td>
                    </tr>
                    <tr>
                        <td>makumba.prefix=value</td>
                        <td>no</td>
                        <td>Hibernate</td>
                        <td>the name of the folder under which the mappings should be generated. by
                            default it is 'makumbaGeneratedMappings'.</td>
                    </tr>
                    <tr>
                        <td>makumba.mdd.root=value</td>
                        <td>no</td>
                        <td>Hibernate</td>
                        <td>the name of the folder in which the MDDs of the webapp are located. If
                            none is provided, the default value is "dataDefinitions".</td>
                    </tr>
                    <tr>
                        <td>makumba.mdd.list=types</td>
                        <td>no</td>
                        <td>Hibernate</td>
                        <td>a comma-separated list of Makumba Data Definitions that should be used.
                            If none is provided, makumba will use all the MDDs in the root folder,
                            if there are.</td>
                    </tr>
                    <tr>
                        <td>makumba.mdd.additionalList=types</td>
                        <td>no</td>
                        <td>Hibernate</td>
                        <td>a comma-separated list of MDDs that should be used in addition to all
                            MDDs found in * the root folder. if none is provided, makumba will use
                            all the MDDs in the root folder, if there are.</td>
                    </tr>
                    <tr>
                        <td>makumba.schemaUpdate=true|false</td>
                        <td>no</td>
                        <td>Hibernate</td>
                        <td>indicates whether makumba should do a schema update with the session
                            factory</td>
                    </tr>
                </table>

                <p> In addition to these parameters, additional parameters can be passed directly to
                the database layer. For additional Hibernate configuration parameters, see:</p>
                <ul>
                    <li><a href="http://www.hibernate.org/hib_docs/v3/reference/en/html/configuration-hibernatejdbc.html">http://www.hibernate.org/hib_docs/v3/reference/en/html/configuration-hibernatejdbc.html</a></li>
                    <li><a href="http://www.hibernate.org/hib_docs/v3/reference/en/html/configuration-optional.html">http://www.hibernate.org/hib_docs/v3/reference/en/html/configuration-optional.html</a></li>
                </ul>
            </section>
        </section>

        <section>
            <title>Controller configuration</title>



        <section>
            <title>Business Logic packages [businessLogicPackages]</title>
            <p> A list of directory=package values that can be used with the Makumba Business
                Logics. See the Business Logic documentation for more information. </p>
        </section>

        <section>
            <title>Authorization [authorization]</title>
        
            <p>This section contains the explicit authorization configuration. See the <a href="/doc/queryfrag.html#explAutho">authorization reference</a> for more details.</p>
        
        </section>
        <section>
            <title>Controller behavior [controllerConfig]</title>

            <table>
                <tr>
                    <th>Parameter</th>
                    <th>Default value</th>
                    <th>Description</th>
                </tr>
                <tr>
                    <td>reloadFormOnError=true|false</td>
                    <td>false</td>
                    <td>Whether the form should be reloaded if a validation error occurs, or whether the action page should be displayed. If a <a href="/doc/taglib/makresponse.html">&lt;mak:response&gt;</a> tag is used, the errors will be displayed there.</td>
                </tr>
                <tr>
                    <td>clientSideValidation=true|false|live</td>
                    <td>false</td>
                    <td>Whether forms are validated client-side. Possible values are <code>false</code> (no client-side validation), <code>true</code> (default client-side validation, that validates only on submission) and <code>live</code> (live validation, that validates fields after input). </td>
                </tr>
                <tr>
                    <td>useDefaultResponseStyles=true|false</td>
                    <td>true</td>
                    <td>Whether the default display style for should be used. If false, the CSS classes <code>makumbaResponder</code> and <code>makumbaSuccess</code> can be used in order to define customized styles for displaying the response.</td>
                </tr>
                <tr>
                    <td>formAnnotation=none|before|after|both</td>
                    <td>none</td>
                    <td>If <code>none</code>, the validation errors will all be displayed in the <a href="/doc/taglib/makresponse.html">&lt;mak:response&gt;</a>. If <code>before</code>, <code>after</code> or <code>both</code>, the form will be annotated with validation errors before, after or before and after the fields.</td>
                </tr>
            </table>
            
            <note>These settings can also be changed at form level. See the <a href="/doc/taglib/makform.html#attributes">mak:form attribute documentation</a> for more details.</note>

        </section>
        </section>
        

        <section><title>Makumba tools</title>
            
            <section id="makToolsPath"><title>Makumba tools path [makumbaToolPaths]</title></section>
            
            <p>Configuration of the path to the Makumba developer tools. By default you don't need to set any of those keys, but if you want to disable a tool, just put an empty value for the key.</p>
           
            <section>
                <title>Makumba developer tools</title>
            </section>
                
            <table>
                <tr>
                    <th>Parameter</th>
                    <th>Description</th>
                    <th>Default value</th>
                </tr>
                <tr>
                    <td>path</td>
                    <td>Root path of the makumba tools</td>
                    <td>/mak-tools</td>
                </tr>
                <tr>
                    <td>mddViewer</td>
                    <td>makumba data definition viewer</td>
                    <td>/dataDefinitions</td>
                </tr>
                <tr>
                    <td>blMethods</td>
                    <td>tool to generate the java body of the makumba business logics</td>
                    <td>/blMethods</td>
                </tr>
                <tr>
                    <td>javaViewer</td>
                    <td>java classes viewer</td>
                    <td>classes</td>
                </tr>
                <tr>
                    <td>logicDiscovery</td>
                    <td>tool that shows the makumba business logics discovery path</td>
                    <td>/logic</td>
                </tr>
                <tr>
                    <td>dataQueryTool</td>
                    <td>tool to query data using MQL or HQL</td>
                    <td>/dataQuery</td>
                </tr>
                <tr>
                    <td>dataObjectViewer</td>
                    <td>a tool to display records of the database, used together with the data query tool</td>
                    <td>/dataObjectViewer</td>
                </tr>
                <tr>
                    <td>dataLister</td>
                    <td>a tool to list records of the database, used together with the data query tool</td>
                    <td>/dataLister</td>
                </tr>
                <tr>
                    <td>referenceChecker</td>
                    <td>a tool to check references (foreign keys) in the database</td>
                    <td>/referenceChecker</td>
                </tr>
                <tr>
                    <td>codeGenerator</td>
                    <td>the makumba code generator, to generate default pages (list, view, create, edit, delete) based on a MDD</td>
                    <td>/codeGenerator</td>
                </tr>
                <tr>
                    <td>objectIdConverter</td>
                    <td><fixme author="manu">rudi, what is this</fixme></td>
                    <td>/dataValueConverter</td>
                </tr>
                <tr>
                    <td>relationCrawler</td>
                    <td>tool used to trigger the crawling of relations between MDD, JSP and business logic files</td>
                    <td>/relationCrawler</td>
                </tr>
                <tr>
                    <td>makumbaCacheCleaner</td>
                    <td>tool that cleans the makumba caches</td>
                    <td>/makumbaCacheCleaner</td>
                </tr>
            </table>
            
            <section><title>Internal Makumba tools</title>
                
                <table>
                    <tr><th>Parameter</th><th>Description</th><th>Default value</th></tr>
                    <tr><td>makumbaValueEditor</td><td>servlet used for in-place edition</td><td>/makumbaValueEditor</td></tr>
                    <tr><td>makumbaUniquenessValidator</td><td>servlet used for uniqueness validation, when using the live validation</td><td>/makumbaUnique</td></tr>
                    <tr><td>makumbaAutoComplete</td><td>servlet that generates answers for the auto-complete</td><td>/makumbaAutoComplete</td></tr>
                    <tr><td>makumbaResources</td><td>servlet that serves resources (stylesheets, javascript) for several makumba features</td><td>/makumbaResources</td></tr>
                    <tr><td>makumbaDownload</td><td>servlet used for the download of <code>file</code> field types</td><td>/makumbaDownload</td></tr>
                </table>
                
            </section>
            
            <section>
                <title>Makumba tools configuration [makumbaToolConfig]</title>
                
                <table>
                    <tr><th>Parameter</th><th>Description</th><th>Default value</th></tr>
                    <tr><td>repositoryURL=value</td><td>The URL to the application repository, used in the source viewer</td><td>http://makumba.svn.sourceforge.net/viewvc/makumba/trunk/makumba/webapps/tests/</td></tr>
                    <tr><td>repositoryLinkText=value</td><td>The text of the repository link</td><td>SVN</td></tr>
                    <tr><td>logErrors=true|false</td><td>Whether Makumba errors should be logged to the database, enabling further analysis</td><td>false</td></tr>
                </table>
                
            </section>
            
        </section>
        
        <section>
            <title>Input style configuration [inputStyleConfig]</title>
            <p>Configuration of input properties (e.g. <code>mak:input</code>).</p>
            <table>
                <tr><th>Property key</th><th>Description</th><th>Default value</th></tr>
                <tr><td>calendarEditor</td><td>Whether the calendar editor for <code>date</code> fields should be active</td><td>false</td></tr>
                <tr><td>calendarEditorLink</td><td>The content of the link to the calendar editor</td><td><![CDATA[<img border="0" src="_CONTEXT_PATH_/mak-tools/makumbaResources/image/calendar.gif"> ]]></td></tr>
            </table>
        </section>
    </body>
</document>
