# Makumba installation guide

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:

1. Prerequisites
2. Creating a basic application
   - Folder structure
   - Deploying the libraries
   - Configuration files
   - Data definitions
   - Example application

## Prerequisites

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 - you can get it right here
- A JSP 2.0 compatible container - we will assume you're using Tomcat 5.0 or higher but using another servlet container is possible, although the configuration might require some server-specific modifications
- A supported SQL engine - we will assume you're using MySQL 4.1 but a list of the supported SQL engines can be found here
- A JDBC driver - for MySQL you should use MySQL Connector/J
- ANTLR - ANother Tool for Language Recognition, (formerly PCCTS), necessary to translate database queries from and to OQL. The following table should help you get the correct ANTLR version for your Makumba library:

  Makumba version | Recommended ANTLR version
  --- | ---
  `?.?.??.? - 0.5.13.8` | `2.7.2`

## Creating a basic application

Now that you've got the tools let's get them to work!

### Folder structure

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

### Deploying the libraries

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

The libraries are in the form of .jar (Java archives). According to the prerequisites you should have three of them:

- `makumba.jar`
- `antlr-?.?.?.jar`
- `mysql-connector-java-?.?.?-bin.jar`

### Configuration files

Don't get too scared! There's very few of them:

- the application deployment descriptor
- the makumba database configuration files

#### Deployment descriptor

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:

    <?xml version="1.0" encoding="utf-8"?>

    <web-app>

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

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

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

#### Database configuration files

Remember talking about the SQL engine. We assumed you were using MySQL. Let's further assume that the database server is located on a computer named `dbhost.yourdomain.org` and 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 `dbhost.yourdomain.org_mysql_maktest.properties` and put it in your application's CLASSPATH, i.e. your `/WEB-INF/classes` folder.

If you're running the MySQL server locally (on the same computer where the Tomcat runs) you can name the database configuration file `localhost_mysql_maktest.properties`.

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:

    # Database configuration file
    # Offset for autoincremented ids
    dbsv=10

    # Username to connect to database
    sql.user=test
    # Password
    sql.password=t

    # Allow Makumba to alter the table structure
    alter#=true

More information on what this file can contain is available here.

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:

    #Default database
    default=dbhost.yourdomain.org_mysql_maktest

### Data definitions

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:

    # Person.mdd
    # Description file for Person entity

    name=not null char[32]  ; Name
    age=not null int        ; Age

More information on Makumba Definition Files

### Example application

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:

    <%@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" %>

    <Persons:>
    <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.

This example might look trivial, if you completed it we invite you to move on to a more complex example. You're all set now!