This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.
The license (Mozilla version 1.0) can be read at the MMBase site. See http://www.mmbase.org/license
Table of Contents
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.
The parameter 'mmbase.htmlrooturlpath' indicates the context root. It must be specified if MMBase does not succeed to determine it automatically, otherwise some URLs to some servlets will be generated incorrectly. Hopefully this option will be deprecated when the servlet 2.3 api is supported well (and fully) by all important application servers. For Tomcat 4.1 it is not necessary, for Orion 1.6 it is.
The parameter 'mmbase.config' indicates the MMBase configuration directory. If this parameter is missing, the configuration is supposed to be in WEB-INF/config (so next to web.xml itself).
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.
If you want to use taglibs in your (jsp) pages - which you probably want - then you may have to indicate that as well in web.xml. Taglibs that you might want to use are the MMBase taglib, the MMBase community taglib, the oscache taglib and the jakarta taglibs. In mosst newer application servers it is enough to have the mmbase-taglib-2.jar (or other jars) in your WEB-INF/lib directory to have the MMBase taglib (or other taglibs) to your disposal.
Since MMBase 1.6 certain things can (optionally) also be configured by the use of references to resources provided by the application server. A resource a an instance of a certain type which is created and configured and can be referred to by a 'resource name'.
These resources must also be described in web.xml. The actual configuration of these resources happens somewhere else and we refer to the documentation of your application server.
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
Example 2. Example java code to start MMBase
try { //MMBaseContext.init("HERE YOUR CONFIG_DIR",true); // no need for -Dmmbase.config then. MMBaseContext.init(); MMBase mmb = (MMBase) MMBase.getMMBase(); // now you have the "MMBase" object // All data can be accessed now. // with the core: MMObjectBuilder images = mmb.getBuilder("episode"); MMObjectNode node=images.getNewNode("admin"); node.setValue("title",(Object) "TEST"); node.insert("admin"); // or nicer, with the bridge: Cloud cloud = LocalContext.getCloudContext().getCloud("mmbase")); NodeManager images = cloud.getNodeManager("episode"); Node node = images.createNode(); node.setField("title", "TEST"); node.commit(); } catch (Exception e) { System.out.println("Something went wrong" + e.toString()); }
'Builder' is another word for 'object-type'. The builder-definitions of your MMBase can be found in config/builders and subdirectories.
This file contains all the settings for one builder
maintainer of the builder defined as a domain
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.jarThe 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
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.
Example 3. An example jdbc.xml
<?xml version="1.0"?> <!DOCTYPE module PUBLIC "-//MMBase/ DTD module config 1.0//EN" "http://www.mmbase.org/dtd/module_1_0.dtd"> <module maintainer="mmbase.org" version="0"> <status>active</status> <classfile>org.mmbase.module.database.JDBC</classfile> <properties> <property name="supportclass">org.mmbase.module.database.DatabaseSupportShim</property> <property name="driver">com.mysql.jdbc.Driver</property> <property name="url">jdbc:mysql://$HOST:$PORT/$DBM</property> <property name="user">mmbase</property> <property name="password">mypassword</property> <property name="database">mmbase_db</property> <property name="host">localhost</property> <property name="port">3306</property> <property name="connections">20</property> <!-- size of connection pool --> <property name="queries">256</property> <!-- connections are refreshed after 256 uses --> <property name="probetime">300</property> <!-- running connections are checked once every 300 s --> </properties> </module>
It is also possible to use the 'data-sources' of the application server. The jdbc.xml then looks like this:
Example 4. An example jdbc.xml, using data-source
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE module PUBLIC "-//MMBase/ DTD module config 1.0//EN" "http://www.mmbase.org/dtd/module_1_0.dtd"> <module maintainer="mmbase.org" version="0"> <status>active</status> <classfile>org.mmbase.module.database.Naming</classfile> <properties> <property name="context">java:comp/env</property> <property name="datasource">jdbc/MMBase</property> </properties> </module>
If you plan to use a application server datasource with the new storage layer, you can also configure this in mmbaseroot.xml. In that case, you do not need the JDBC module, and can set it to inactive. See the storage documentation for details.
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.
The logging system is set up with the file config/log/log.xml, which is an XML file with two entries:
The class which implements the logging. The mmbase.jar provides now two classes which can be used for this.
org.mmbase.util.logging.SimpleImpl
Provides a very simple implementation, which 'logs' on stdout or stderr. So it can not even log to a file by itself.
org.mmbase.util.logging.log4j.Log4jImpl
This is the advised and default. This implementation is based on the log4j system, and if this one is chosen, the log4j.jar is required. The version of log4j.jar must be 1.2.
A string to configure the logging system. For 'SimpleImpl' this is: stderr|stdout[,<logging level>]. So you can only decide where the logging must appear, and below which level it should not log (the same levels as in the log4j implementation). For Log4jImpl it is a file name, in which the configuration is. This is an XML file according to the 'DOMConfigurator' of log4j. The rest of this document will give a short description of how this file looks like.
The MMBase implementation of log4j has the following logging levels (from low to high).
In the log4j implementation it is per category possible to set the 'logging level', which means that only above (and on) that level will be logged. In 'simple' implementation only one logging level can be set (and categories are ignored).
In the log4j configuration file for log4j versions 1.1 and lower levels are called 'priorities'.
Everything which is described here will be much quicker clear if you have a few examples handy. A few are checked in the MMBase CVS with the names 'log4j.xml' (default), 'log4j.example1.xml' (use of two appenders), 'log4j.example2.xml' (XMLLayOut), 'log4j.example3.xml' (extra appender for important things). A few were provided by the log4j project itself too.
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:
Example 5. Appenders
<appender name="logfile" class="org.apache.log4j.FileAppender" > <param name="File" value="&logdir;mmbase.log" /> <param name="Append" value="true" /> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d{ABSOLUTE} %-5p - %m%n" /> </layout> </appender>
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:
Example 6. Category
<logger name="org.mmbase.security" additivity="false" > <level class="&mmlevel;" value ="info" /> <appender-ref ref="securityfile" /> </logger>
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.
Example 7. Caches
<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE caches PUBLIC "-//MMBase/DTD cache config 1.0//EN" "http://www.mmbase.org/dtd/caches_1_0.dtd"> <caches> <!-- ================================================================================ Node caches ================================================================================ --> <!-- simple nodes --> <cache name="Nodes"> <status>active</status> <size>4096</size> </cache> ..... </caches>
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.
Some words about XML, XML Entities and so on. Not directly related to MMBase.
The format of XML's is defined by dtd's. All MMBase specific XML's (recognizable by the DOCTTYPE) are validated when parsed (from MMBase 1.6 onwards). This means that the dtd's for all these XML type must be available. They are available in the mmbase.jar, so you normally will not have to worry about them. You can store them in config/dtd where MMBase will find them first, so you could override the ones in the jar (useful during development). It they cannot be found, validation will occur with an empty DTD, resulting in lots of errors in your log.
Since MMBase 1.8 also some XML's are defined by XML Schema Definitions. For example config/datatypes.xml and the new version of the builder XML's (with support for datatypes). There is no DOCTYPE on such XML's but the root element defined a namespace and 'schemaLocation'. The schema is resolved in a similar way as DTD's are resolved.
If you don't want XML's to be validated, then you can place a configuration file config/utils/documentreader.xml (the default version is in mmbase.jar), and change it. This can be useful to avoid the overhead, or avoid the warning which may fill the log if you have a lot of legacy XML's (e.g. some people shipped a zillion of non-validating editwizard definitions).
Validation of non MMBase specific xml's, like web.xml and 'log4j.xml' is left to the applications responsible for them (application server and log4j in these cases).
This is part of the MMBase documentation.
For questions and remarks about this documentation mail to: [email protected]