Overview of Melati (document $Revision: 1.2 $)

Introduction

What is Melati for?

Melati is an open source, Java-based infrastructure for the rapid and convenient development of web-based database applications. It addresses the following problems typically encountered in the development of complex sites:

How does Melati work?

The entry points to a Melati application are a set of one or more servlets derived from TemplateServlet. There are subtypes for different template engines. It takes care of determining the Melati username associated with the client, and the `logical database' on which the servlet should operate from the path info: for instance, the URL

http://melati.org/db/org.melati.admin.Admin/melatitest/user/View

asks the Admin servlet (Admin.java) to " View the user table of the melatitest database". This scheme has the (admittedly minor) advantage that it makes possible the use of concise relative URLs for many purposes.

If it has not already been encountered by the running virtual machine, the logical database name is mapped to JDBC connection details via the config file org.melati.LogicalDatabase.properties. When the first JDBC connection has been established (i.e. once per JVM), a picture is built up of how the structure-database ought to look, drawing on the programmer's compile-time Data Structure Definition (DSD), if any, and on the type-rich metadata set up by the administrator using the generic admin interface. This picture is then unified, or reconciled, with the actual database structure reported by JDBC's DatabaseMetadata. In effect, the structures specified by the three sources are added together and merged; any tables or columns present in the underlying DBMS but not specified by the programmer or administrator are incorporated (and have default metadata records created for them), while conversely any tables or columns specified by the programmer or administrator but not present in the DBMS are created. If the unification cannot be completed consistently (e.g. if the underlying database has been incompatibly altered), the connection is aborted.

The end result of all this as far as the Java code is concerned is a natural and convenient representation of the database in terms of Database, Table and Column objects. Columns have rich PoemType types which include information such as the target of a reference (link) or the default height of a text field; but in general one works directly in terms of Persistent objects representing the rows in the database.

In coding up the application logic, the programmer accesses the rows' fields using statically named and typed methods autogenerated at compile time from the Data Structure Definition. For more on this, see the Melati POEM User Guide.

Template writers can simply ask for the appropriate field value and let the MarkupLanguage of their choice render it appropriately. For instance, assuming that an application servlet has set $product to refer to some Persistent object, one could say

#set $Response.ContentType = "text/html"
#set $ml = $melati.HTMLMarkupLanguage
<HTML>
<BODY>

<P>
  You have asked for a $ml.rendered($product.NameField),
  which has to come from $ml.rendered($product.CountryField)
  at a cost of $ml.rendered($product.Country.PriceField).
<P>

</BODY>
</HTML>

The ...Field idiom returns a value wrapped up with a PoemType which the markup language $ml (set to HTML at the top of the template) knows how to render. Note the phrase $product.Country.PriceField, in which a reference (link) to a record in the country table is transparently followed.

Generating input controls for objects' fields is just as easy. The following simplified fragment of a template from the generic admin system (Edit.wm, also illustrates how you can iterate over all the fields in an object without having to know their names:

<TABLE>
  #foreach $field in $object {
    <TR>
      <TD>
        $ml.rendered($field.DisplayName)
      </TD><TD>
        $ml.input($field)
      </TD>
    </TR>
  }
</TABLE>

Behind the simple phrase $ml.input($field), Melati is

Part of the point of having type-specific templates is that they can carry JavaScript (VBScript, ...) routines for client-side validation of the values entered or otherwise selected by the user. For instance, this is template/webmacro/templets/html/org.melati.poem.IntegerPoemType.wm :

<INPUT NAME="field_$ml.rendered($field.Name)" SIZE=$field.Width
       VALUE="$ml.Attr.rendered($field.RawString)">

<SCRIPT LANGUAGE=JavaScript1.2>
  add_integer("field_$ml.escaped($field.Name)",
              "$ml.escaped($field.DisplayName)",
	      !$field.Type.Nullable)
</SCRIPT>

You can see at the top and bottom of Edit.wm how these JavaScript fragments fit into the overall template.

Where to go from here?

Resources

Melati's home on the web, http://melati.org , provides information, mailing lists and CVS access.

A simple example

See the Example.

Installing Melati

The README has installation details.

Guides to Melati's component parts

Document    Description
org.melati.poem   

Of interest to programmers.

Melati POEM (Persistent Object Engine for Melati) is what gives Melati its object-oriented view of the underlying relational database. It maintains type information about database fields, and handles connection pooling, cacheing and access control. POEM is independent of the rest of Melati and could be used for non-web applications.

org.melati.poem.prepro   

Of interest to programmers.

POEM's preprocessor is responsible for turning concise, Java-style "Data Structure Definitions" into boilerplate code for creating a corresponding relational database and representing it as a collection of typed objects.

org.melati.template   

Of interest to page authors.

Melati's API is Template Engine agnostic. Melati can be used with Webmacro or Velocity or both, as Webmacro templates are converted on-the-fly to Velocity templates.
Melati comes with default templets for rendering fields for input and output in HTML or WML. The templets can be overridden or added to.

org.melati.admin
  

Of interest to most users.

The generic database administration system supports "out of the box" content editing.

Frequently asked questions

Go on, ask a question on the Mailing Lists!