MMBase Configuration documentation


Table of Contents

1. Introduction
2. Web.xml configuration
2.1. Context parameters
2.2. Servlets
2.3. Taglibs
2.4. Resources
2.5. Example
3. Running MMBase without a web.xml
4. Builders
4.1. builder.dtd , builders as urls,people,images ...
5. Databases
6. Configuring logging
6.1. Setting up the logging system
6.2. Logging levels.
6.3. Configuring the log4j implementation
6.3.1. Examples
6.3.2. Loggers/Categories
6.3.3. Appenders
7. Caches
A. XML
1. DTD's, XSD's and validation
2. XML Entities

The MMBase configuration can normally be found in WEB-INF/config. Optionally, it is also possible to store this configuration in another directory, which then has to be done by use of the web.xml context parameter 'mmbase.config'. In this document, this configuration directory will be simply referred to as 'config'.

The base of a web application configuration is always the so-called 'web.xml'. In a web.xml the following MMBase specific things could be found.

For MMBase to start up, at least one 'MMBaseServlet' must be turned on in your web.xml. The following of those servlets are available.

org.mmbase.servlet.MMBaseServlet

MMBaseServlet itself is the most basic MMBaseServlet, which can be used to serve the MMBase version number. It has no properties to be set. You don't need a servlet-mapping to it (if you only want to use it to start up mmbase), though "/version" would be nice (and specified as such in the MMBase distro).

If mapped to an URL, then it also recognizes a few parameters like 'uptime', 'starttime' and 'server', which, when supplied, make the servlet return, besides the mmbase version, also some system information.

org.mmbase.servlet.ImageServlet

This servlet serves MMBase nodes as images (so also icaches). Those nodes must contain an 'handle' field. It has an 'expire' property, which can be set to specify the 'Expires' header (for the node-type 'icaches' this is ignored) in seconds after now. A servlet-mapping could be e.g. /images/* or /img.db.

The image servlet also recognizes a 'convert' property, which may be `true', in which case it will also accept image conversion templates in the URL. This can be switched to true for backwards compatibility with `servdb' for which this was the way to specify a icache node.

If you switch this to true, you may also want to switch on a 'mmbase.taglib.image.urlconvert' context parameter, which will make the image-tag produce these kind of URL's. In 1.8 this does not make much sense, because image-transformation would be postponed to image serving any way. But it is possible any way (from 1.7.4 onwards).

It is also possible to have the images served by another web-application (which you might want for certain load-balancing reasons). In that case you don't specify the servlet, but only a context parameter 'mmbase.servlet.images.url', containing the absolute URL to the image-servlet on the other web-app (so this other MMBase must run on the same database!).

org.mmbase.servlet.AttachmentServlet

This servlet looks a lot like ImageServlet, but it is focused on 'attachments' nodes, which besides a 'handle' also store a 'mimetype' field and a 'filename' field. It has the 'expire' property just like ImageServlet. Map it e.g. to /attachments/* or /attachment.db.

The attachments can, similar to images, also be served from a different server. Using the context paramter 'mmbase.servlet.attachments.url'

org.mmbase.servlet.servdb

This servlet is the original one of MMBase 1.5 and before. It can do several things and is normally mapped to e.g. /img.db and /attachment.db. By the mapping it decides what to do.

When it is used as an 'imageservlet' it also can accept the 'transformation' template to generate a 'icache' node from a original image node on the URL. This can be handy, but also opens a vulnerability to your site.

Since servdb is not based on the MMBase bridge, the content which it serves is not protected by the security system. It will serve any image, attachment etc. disregarding the possible read-restrictions on them.

The implementation of this servlet is nowadays only available in mmbase-scan.jar, and it's use is deprecated.

org.mmbase.servlet.servscan

If you also have turned on the right MMBase 'modules', this servlet will provide the 'SCAN' template language. For new users it is advised not to use SCAN, but to use e.g. JSP (the JSP servlet and servlet-mapping are normally shipped with and installed in your application server). The SCAN servlet servscan has to be mapped to '*.shtml'.

The implementation of this servlet (and of the SCAN language) is nowadays only available in mmbase-scan.jar, and it's use is deprecated.

Here is an example web.xml. Some things are clarified more by use of XML comments in it.

Example 1. An example web.xml

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>

    <!-- comment out if necessary (only in older app-servers)
    <context-param>
        <param-name>mmbase.htmlrooturlpath</param-name>
        <param-value>/mm/</param-value>
    </context-param>
    -->
  <!--
    If you want to serve images from a different server, then you can specify the complete URL to
    the images-servlet in this property.
    The same goes for other 'servlet associations' like 'attachments' and 'downloads'.
    -->
  <!--
  <context-param>
    <param-name>mmbase.servlet.images.url</param-name>
    <param-value>http://www.myclub.com/mmbase18images/mmbase/images/</param-value>
  </context-param>
  -->


    <servlet>
        <servlet-name>version</servlet-name>
        <servlet-class>org.mmbase.servlet.MMBaseServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet>
        <servlet-name>images</servlet-name>
        <display-name>images</display-name>
        <servlet-class>org.mmbase.servlet.ImageServlet</servlet-class>
        <init-param>
            <param-name>expire</param-name><!-- Expire time of original images. Cached images never expire -->
            <param-value>600</param-value><!-- 10 minutes -->
         </init-param>
        <init-param>
            <param-name>convert</param-name><!- Whether to accept convertion templates -->
            <param-value>false</param-value><!-- no -->
         </init-param>
        <load-on-startup>2</load-on-startup>
    </servlet>

    <servlet>
        <servlet-name>attachments</servlet-name>
        <display-name>attachments</display-name>
        <servlet-class>org.mmbase.servlet.AttachmentServlet</servlet-class>
        <init-param>
            <param-name>expire</param-name><!-- Expire time of attachment -->
            <param-value>600</param-value><!-- 10 minutes -->
        </init-param>
        <load-on-startup>3</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>version</servlet-name>
        <url-pattern>/version</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>images</servlet-name>
        <url-pattern>/images/*</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>attachments</servlet-name>
        <url-pattern>/attachments/*</url-pattern>
    </servlet-mapping>

    <!-- The MMBase taglib
  In Tomcat 5, this section can be left away (it will detect the jar by itself)
  -->
    <taglib>
        <taglib-uri>http://www.mmbase.org/mmbase-taglib-1.0</taglib-uri>
        <taglib-location>/WEB-INF/lib/mmbase-taglib.jar</taglib-location>

        <!-- specifying a jar should work according to specs, but does not (yet) in all app-servers
                 if loading the taglib fails, use a separate taglib description file -->
        <!-- <taglib-location>/WEB-INF/mmbase-taglib.tld</taglib-location> -->
    </taglib>

    <!-- MMBase community taglib
  In Tomcat 5, this section can be left away (it will detect the jar by itself)
  -->
    <taglib>
        <taglib-uri>http://www.mmbase.org/mmcommunity-taglib-1.0</taglib-uri>
        <taglib-location>/WEB-INF/lib/mmbase-community.jar</taglib-location>

        <!-- or use a separate taglib description file  -->
        <!-- <taglib-location>/WEB-INF/mmcommunity-taglib.tld</taglib-location> -->
    </taglib>

    <!-- Taglibs not directly related to MMBase -->
    <!--
        The 'Open Symphony' cache tags can e.g. cache your page partially. It uses expire-times or can
        be invalidated programatically.  See http://www.opensymphony.com

    In Tomcat 5 (and using a recent oscache!), this section can be left away (it will detect the jar by itself)
    -->
    <taglib>
        <taglib-uri>oscache</taglib-uri>
        <taglib-location>/WEB-INF/lib/oscache.jar</taglib-location>
    </taglib>

 <resource-ref>
        <description>
            Email module mail resource (JMSendMail). This resource must be
            configured in the application server. See also config/modules/sendmail.xml.
        </description>
        <res-ref-name>mail/MMBase</res-ref-name>
        <res-type>javax.mail.Session</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>

    <resource-ref>
        <description>
            Datasource for the MMBase Database. This datasource must be
            configured in the application server. See also config/modules/jdbc.xml
        </description>
        <res-ref-name>jdbc/MMBase</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>

</web-app>

                    

Sometimes it is useful to run (parts of) MMBase outside a servlet environment, for example when you are a developer and want to test only a certain part without the overhead of starting up a whole application server. Another example is when you make a data-importer.

In such cases the JVM option (-D) mmbase.config might come in handy, because most parts of MMBase somehow do need a configuration. It might be for example only to configure the logging system.

In older MMBase versions it was required to use this JVM option even when you did run it as a (set of) servlet(s), but this is not any longer the case (since MMBase 1.4), and use of '-Dmmbase.config' other then in debugging or other 'stand-alone' situations is discouraged.

In these older versions of MMBase also the 'mmbase.htmlroot' command line option was needed. It still is supported (though not by JSP), but I can't think of any situation in which it would be needed (besides when using a very old MMBase or perhaps a very old application server), and I think this option can now be considered fully deprecated. --> perhaps in junit tests?

To complete this description of how to run MMBase outside a servlet environment


You have to make sure that mmbase.jar and your servlet.jar are in the classpath. The above code shows you how to access the MMBase Data.

'Builder' is another word for 'object-type'. The builder-definitions of your MMBase can be found in config/builders and subdirectories.

In the databases subdirectory of the configuration you find the XML's describing supported databases. These files are only used by the old (pre-1.7) database layer of MMBase. If you intend to use the new Storage layer (recommended), you can remove this directory. For configuration of the new Storage Layer, see the storage documentation.

Even when you use the old database layer, in an actual installation all but one of these files can be removed. It must correspond to the 'database' property in config/modules/mmbaseroot.xml, if this property is present. You can also remove the database property from mmbaseroot.xml (I would advice this, because then all database configuration is in jdbc.xml), then the 'lookup.xml' file will be used to determine the right database configuration XML (so perhaps it is better to leave them) using the available driver.

It is important to make the right driver available, anyhow. This is usually done by putting the right jar in WEB-INF/lib.

com.mysql.jdbc.Driver from mysql-connector-java-2.0.14-bin.jar

The mysql driver can be downloaded from The mysql website

org.postgresql.Driver from pg73jdbc2.jar (make sure to have a version which works with your postgresql version / jdk)

The postgresql driver can be downloaded from The postgresql website

Support for other databases is also present in MMBase. The file 'config/databases/lookup.xml' should give some impression about which drives are known to work.

The file in which is configured which driver MMBase must use is config/modules/jdbc.xml. Other information for this driver can also be included. Here you can configure the username/password for access to the database, the database name itself, the port number on which the database is listening etc.


It is also possible to use the 'data-sources' of the application server. The jdbc.xml then looks like this:


So using this the configuration of the database is totally left to the application server.

This section describes how the logging facilities of MMBase can be configured. It will focus on the default configuration, which is based on log4j.

Information about concepts of log4j can be found here.

A category is chain of string separated by dots, which works a little like name-spaces. This means that "A.B.C" is in the "A.B" category, and "A.B" is in the category "A".

In MMBase it was chosen that categories fall together with Java class / package names. So if you want to set logging level for everything related with the security implementation you have to set the category "org.mmbase.security". All MMBase classes/packages can be found on www.mmbase.org.

In the MMBase log4j implementation one extra category is defined, namely 'STDERR'. Everything which is produced on stderr somewhere in the mmbase code will be redirected to this logging category with priority (level) 'info'. Normally, this will not be much, but it can be handy during debugging of - for example - jsp pages.

'Categories' inherit properties from each other (if nothing is overridden, then 'A.B.C' is like 'A.B'), and there is one 'root' category, from which all categories inherit.

In the log4j XML configuration file, categories are present as 'logger' tags ('category' in older versions). The name attribute of the logger tag contains the category, the previously described string, which coincides with Java classes/packages.

A special category is 'root', which describes the basic properties of all categories. It is described with the 'root' tag.

The logging 'level' can be set per category/log by a sub tag of 'logger', named 'level'. The level class was overridden by MMBase so the 'class' attribute must be present on every occurrence. The value of this can be stored in an XML entity (&mmlevel;). The actual value is set by the 'value' attribute.

The root tag must appear after the logger tags.

Think of an appender as a 'log file'. You can configure several appenders. Here is a typical appender configuration:


Here is described that the appender is a file, and that the filename is 'mmbase.log' in the directory described by the entity &logdir;. It appends the logging to the end if the files exist already. The precise format of one line is described too, and is in this case defined by the Java class "org.apache.log4j.PatternLayout". The documentation of this class, and of the 'ConversionPattern' parameters can be found here. The conversion pattern can have an influence on the over all performance, so you have to be careful with it.

Normally the root category will specify to which appender all categories will log (The appender-ref tag in the root tag). A category can specify an additional appender. If you want to avoid that this category also logs to the appender of 'root' you can use the attribute 'additivity' of the category tag.

It would e.g. be interesting to log security related issues to a separate logfile, but not to the 'main' log file. Then a new appender must be defined, with name 'securityfile', and the category entry for 'org.mmbase.security' could look like this:


Per 'FileHandler' also the parameter 'Threshold' can be set, which makes it possible to set the logging priority for an appender, which means that logging events below this threshold are not logged to this appender regardless of the setting of the category.

This describes the functionality of log4j as far as we foresee needing it. As one can see in the log4j javadoc there is much more functionality available (specialized appenders (for example which are rotated), layouts etc).

MMBase has several caches, which can be configured by a file 'caches.xml' which must be in in the MMBase configuration directory.

Since MMBase-1.8 also the strategies which must be used to invalidate entries in Query caches can be configured in this file.


As can be seen in this example, per cache can be configured if it should be active or not and how big it should be.

In caches.xml itself you should see which caches can be configured, and also a description about what exactly they actually cache. Defaults cache sizes are chosen to be reasonable, deviating from the defaults should be done with good reason.

A. XML

Some words about XML, XML Entities and so on. Not directly related to MMBase.


This is part of the MMBase documentation.

For questions and remarks about this documentation mail to: [email protected]