MMBase Configuration documentation


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 can only serve the MMBase version number. It has no properties to be set. You don't need a servlet-mapping to it, tough "/version" would be nice.

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.

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.

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.

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'.

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
	<context-param>
		<param-name>mmbase.htmlrooturlpath</param-name>
		<param-value>/mm/</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>
		<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 -->
	<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 -->
	<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
	-->
	<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).