This is a quick guide to help you get Makumba up and running. In this document we will show you how to deploy a simple Makumba application covering the following steps:
So, you want to start building apps with Makumba? You're on the right track, now let's make sure you have the right tools! This is what you need:
| Makumba version | Recommended ANTLR version |
|---|---|
| ?.?.??.? - 0.5.13.8 | 2.7.2 |
Now that you've got the tools let's get them to work!
With Tomcat you deploy each application in a subfolder of webapps. We will further on refer to this subfolder as the root folder of your application. This being a test, let's name it maktest.
In order to be a valid web module, this root folder of your application should contain a WEB-INF folder. This is where you should have your web.xml deployment descriptor and the classes and lib folders.
This is how the folder structure is supposed to look like:
maktest/ WEB_INF/ classes/ lib/ web.xml
In order for the libraries to be accessible they should be placed either in your Tomcat's /common/lib folder of in your application's /WEB-INF/lib folder.
Putting them in the /common/lib folder will make them accessible to all applications deployed in the container but we recommend using the application-specific folder (at least for this example).
Don't get too scared! There's very few of them:
This is the /WEB-INF/web.xml file we've mentioned before. Here's a basic example of what it should look like if you're using Tomcat.
maktest/WEB-INF/web.xml<?xml version="1.0" encoding="utf-8"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <!-- Makumba Controller Filter, needed to invoke e.g. form responders --> <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> <!-- Developer support - MDD & Business logic browser & viewer --> <servlet> <servlet-name>mddLinker</servlet-name> <servlet-class>org.makumba.devel.SourceViewServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>mddLinker</servlet-name> <url-pattern>*.jspx</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>mddLinker</servlet-name> <url-pattern>*.jspxp</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>mddLinker</servlet-name> <url-pattern>/dataDefinitions/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>mddLinker</servlet-name> <url-pattern>/classes/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>mddLinker</servlet-name> <url-pattern>/logic/*</url-pattern> </servlet-mapping> <!-- Developer support - query tool --> <servlet> <servlet-name>dataQuery <servlet-class>org.makumba.devel.DataQueryServlet </servlet> <servlet-mapping> <servlet-name>dataQuery <url-pattern>/dataQuery/* </servlet-mapping> <!-- Developer support - single data object viewer --> <servlet> <servlet-name>dataViewer <servlet-class>org.makumba.devel.DataObjectViewerServlet </servlet> <servlet-mapping> <servlet-name>dataViewer <url-pattern>/dataView/* </servlet-mapping> <!-- Developer support - data lister --> <servlet> <servlet-name>dataLister <servlet-class>org.makumba.devel.DataTypeListerServlet </servlet> <servlet-mapping> <servlet-name>dataLister <url-pattern>/dataList/* </servlet-mapping> <!-- Developer support - pointer value converter --> <servlet> <servlet-name>dataValueConverter <servlet-class>org.makumba.devel.DataPointerValueConverter </servlet> <servlet-mapping> <servlet-name>dataValueConverter <url-pattern>/valueConverter/* </servlet-mapping> <servlet> <servlet-name>invoker</servlet-name> <servlet-class>org.apache.catalina.servlets.InvokerServlet</servlet-class> <init-param> <param-name>debug</param-name> <param-value>0</param-value> </init-param> <load-on-startup>2</load-on-startup> </servlet> <servlet-mapping> <servlet-name>invoker</servlet-name> <url-pattern>/servlet/*</url-pattern> </servlet-mapping> </web-app>
Remember talking about the SQL engine. We assumed you were using MySQL. Let's further assume that the database server runs on your computer, having the hostname localhost and that you'll be using a database named maktest to store the tables for this application. For Makumba to know where and how it should connect to the database you need to create a file named localhost_mysql_maktest.properties and put it in your application's CLASSPATH, i.e. your /WEB-INF/classes folder.
This file will contain the username and password to connect to the database and a line that instructs the Makumba engine to create or alter any needed table structure (you should comment this out after creating the final table structures). Here's an example:
maktest/WEB-INF/classes/localhost_mysql_maktest.properties# Database configuration file # Offset for autoincremented ids dbsv=10 # Username to connect to database sql.user=test # Password sql.password= # Allow Makumba to alter the table structure alter#=true
As Makumba is able to work with multiple databases, you need to instruct it where to get it's default settings from. This is done via the MakumbaDatabase.properties file, also located in your CLASSPATH. In this case:
maktest/WEB-INF/classes/MakumbaDatabase.properties#Default database default=localhost_mysql_maktest
In order to be able to manipulate information from a database Makumba needs to know what this info looks like. For each table you're using you need to provide a data definition file. We recommend putting these files in a special folder: WEB-INF/classes/dataDefinitions and giving them an *.mdd extension. For example:
maktest/WEB-INF/classes/dataDefinitions/Person.mdd# Person.mdd # Description file for Person entity name=not null char[32] ; Name age=not null int ; Age
Now we have anything we need to run the first Makumba-powered application. Let's create an index.jsp file in our applications root folder:
maktest/index.jsp<%@page contentType="text/html"%> <%@page pageEncoding="utf-8"%> <html> <head><title>Person list</title></head> <body> <%@taglib uri="http://www.makumba.org/presentation" prefix="mak" %> <h1>Persons</h1> <mak:list from="Person p"> <mak:value expr="p.name"/>, <mak:value expr="p.age"/> <br/> </mak:list> </body> </html>
Now, if everything went right, running this should return a page with the text Persons:. If you're getting an error check to see you've done everything right. Running this simple app should have also created a table named person_ in your maktest database. Add some records into that table and run the application again. You should get a list of persons and ages.