Makumba Specification

Makumba in Java Server Pages

Makumba tags are written according to Servlet 2.3 specification and JSP 1.1 specification. You will need a so-called "servlet container" that supports them both, such as Apache Tomcat. The corresponding WEB-INF/makumba.tld is already included in the distribution makumba.jar. The example WEB-INF/web.xml can be found in Makumba cvs repository.

Before using Makumba tags in your JSP pages you also need to declare the taglib with:

<%@ taglib uri="http://www.makumba.org/presentation" prefix="mak" %>

A few resources on JSPs (don't be afraid to try first, read later) :

• JSP documentation by Sun
• J2EE web services documentation by Sun. This is an introduction on the various technologies that you might use when building webapplications using Java2 (J2EE).
• Gentle introduction to JSPs

Makumba Controller

The makumba controller is a component running in the 'servlet container'. When a request for a makumba page enters the servlet container, the controller will intercept the request, and perform its "controller" activities (cfr. the model-view-controller pattern) :

• checking if the page has the appropriate attributes (see handler initialisation; e.g. force login).
• checking if the page request is the result of a form submit or a deleteLink. If so, perform the relevant actions in the handler and database.
• deal with problems (exceptions) during the controller activity:
  • if org.makumba.LogicException is thrown, the Exception can write a message to the <mak:response> in the requested page.
  • org.makumba.UnauthenticatedException and org.makumba.UnauthorizedException will force login (although UnauthorizedException probably shouldn't, bug 444)
  • if another exception occurs, an errorPage will be shown instead of the requested page.

For this to work, the correct configuration must be applied in WEB-INF/web.xml (example file). The following would tell the makumba controller to filter all requests for .jsp files.

  <filter>
     <filter-name>makumba_controller</filter-name>
     <filter-class>org.makumba.controller.http.ControllerFilter</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>makumba_controller</filter-name>
    <url-pattern>*.jsp</url-pattern>
  </filter-mapping>

Note that if (in this example) the result page for a makumba form would be an .html page, then the makumba controller would not intercept the .html page request, and the actions implied by the form, would not be performed.

JSP tag parameters

JSP-tag parameter values are either FIXED or RTEXPR (runtime expression). A FIXED tag parameter must have a constant, literal value, while an RTEXPR can also be of the form <%= java_expression %>. On the other hand, some FIXED parameters can contain jsp attributes like $attr in makumba tags.

All parameters are optional unless specifically mentioned as being mandatory.

Specific concern can be the parameter quoting. Tag parameters can be written as name="value" or name='value' (note: the stringLiteral on DATE must be quoted with "). The choice of quote can be determined by the need to use either double or single quote as part of the value itself. If the quote is also present within the value, it must be escaped by a backslash.

  <mak:list from="general.Person p" where="p.gender=\"male\"" >
  <mak:list from="general.Person p" where='p.gender="male"' >
  <mak:list from="general.Person p" where="p.gender='male'" >
  <mak:list from="library.Book b" where="b.publisher=\"O'Reilly\" " >    
  <mak:list from="library.Book b" where='b.publisher="O\'Reilly" ' >

Quotes in extra HTML formatting parameters, such as styleClass, title, styleId, onClick ... need some special attention with quotes. The parameter values are copied verbatim (with no modifications by makumba) to the resulting HTML, always surrounded with double quotes ("). This means that you have to use other quotes, like single one ('),
If you need to pass a literal backslash (\) you have to escape it with a preceeding backslash (\\).

  <mak:input ... onClick="alert(this.value);"/>
  <mak:input ... onClick="alert('Hello world!');"/>
  <mak:input ... onClick="alert('Hello\\nWorld');"/>

Unfortunately the idea to use a sequence of escapes, eg writing \\\' in the JSP page to set the tag attribute to \', which could be handy for javascript tag attributes, is confusing the Tomcat servlet container.

<mak:response/>

<mak:response/> prints information about the results of the actions that were performed by the makumba controller (e.g. for a form submit or deleteLink): It either displays the message="..." parameter of the form tag (in green) in case of success, or (in red) the message of a uncaught LogicException resulting from Business Logic. Other exception types will provoke an exception page.

The unformatted message is available as request-scope attribute makumba.response. The jsp page can get hold of the message using e.g.

<% String s = (String) request.getAttribute("makumba.response") %>

Similarly, request-scope attribute makumba.successfulResponse is set only in case of successful action execution.

<% if (null == request.getAttribute("makumba.successfulResponse")) { /* action failed */ } %>

(A body-tag style (<mak:response>...</mak:response>) will be added later, to display different messages for different circumstances (errors). It will also be possible to get hold of the actual exception object. )