The Melati Project

Tim Pizey

Last change $Date$, by $Author$ At melati.org

Contents:

About Melati

Melati is a tool for building Java-programmed websites backed by a database. It provides the following features:

Melati's design builds on our experience with previous systems we have deployed successfully on a number of commercial sites: we feel that it enables a particularly elegant and productive way of working.

 

 

Release Notes

See the release notes for detailed documentation about what has changed. This is the 25rd beta release of Melati, offering the following improvements over Alpha versions of Melati:

 

Upgrading

To upgrade from Melati 0.7.4 to Melati 0.7.9

  1. No changes required.

To upgrade from Melati 0.7.4 to Melati 0.7.5

  1. Move any templets from, for example, org/melati/template/webmacro/template/html to org/melati/templets/html.

To upgrade from Melati 0.7.4 to Melati 0.7.5

  1. You will need to change references to org.melati.servlet.MelatiContext to org.melati.PoemContext and remove direct access to its members, use the setters and getters.

    References to MelatiUtil.getFormNulled etc should now use the same methods in org.melati.servlet.Form.

To upgrade from Melati 0.7.3 to Melati 0.7.4

  1. You will need to change melati-static to point to /dist/melati/src/main.

To upgrade from Melati 0.7.1 to Melati 0.7.3

  1. This release refactors the source tree so you should change melati-static to point to ...melati/src/main/org/melati

    You can now use webmacro templates inside the Melati jar, so have no need for a duplicate set of templates outside the jar.

To upgrade from Melati 0.7.0 to Melati 0.7.1

  1. This release adds support for BigDecimal types. This requires the addition of two fields to the field meta data: scale and precision. Consequently existing columninfo and setting tables need to be altered. The easiest way is just to drop these tables and allow Melati to recreate them. Unless your settings are ensured you will have to reenter them. If you are running postgresql 7.3 or higher you should be able to do the following instead: 

    ALTER TABLE setting ADD COLUMN scale int;
ALTER TABLE setting ADD COLUMN precision  int;
ALTER TABLE setting ALTER COLUMN scale SET NOT NULL;
ALTER TABLE setting ALTER COLUMN precision SET NOT NULL;

To upgrade from Melati 0.6.* to Melati 0.7.0

  1. You will have to upgrade your Postgresql installation to at least 7.3, so as to use the driver supplied with Melati. Note that recent versions of Postgresql require a character set to be specified at db creation time.

To upgrade from Melati 0.55.* to Melati 0.6.*

  1. No known upgrade issues - working with Postgres 7.1, WebMacro 1.0, Velocity 1.2, MySQL-Max 3.23.49

To upgrade from Melati 0.54.* to Melati 0.55.*

  1. You should upgrade to WebMacro 0.98p1. This has improvements to whitespace handling, and fixes a bug where some Parse Exceptions where thrown as Errors, causing Internal Server Errors, and not tidying up Poem Transaction

  2. if you have specialised org/melati/error.wm for your site, you will have to rename your version to org/melati/template/webmacro/templets/html/error/java.lang.Exception.wm

 

To upgrade from Melati 0.53.5 to Melati 0.54, 0.54.1 or 0.54.2

  1. You must upgrade to WebMacro 0.98.
  2. If you construct your own FastWriter, you need to supply a Broker to the constructor.
  3. If you use a PassbackExceptionHandler (in order to render AccessPoemExceptions inline in the page), you will need to set it by using: $melati.setVariableExceptionHandler($melati.PassbackVariableExceptionHandler) in your templates.

 

To upgrade from Melati 0.53.4 to Melati 0.53.5

You will probably not need to make any changes, but you should be aware of the following:

1) We no longer provide a getXxxxDatabase() function in each Table and Persistent. Instead you should either just use getDatabase() or you can use getXxxxDatabaseTables() to access tables specific to your project. In particular, getPoemDatabase() is no longer available in the Poem tables/persisents. So if you call getPoemDatabase() in your code, you should change it one of getDatabase() or getPoemDatabaseTables(). Similarly, if you re-run DSD on your project Xxxx then you will need to handle any calls to getXxxxDatabase(). You can either change them to getXxxxDatabaseTables(), getDatabase(), or you can add the old function into your non-generated files: e.g. in MyTable.java add:

 XxxxDatabase getXxxxDatabase() { 

    (XxxxDatabase)getDatabase();

 }

2) I have tested this on several databases and although I am fairly confident that it should work, IF YOU RE-RUN DSD ON YOUR OWN DATABASES YOU MAY EXPERIENCE PROBLEMS.

3) Your .dsd file must live in the same directory as your compiled code because it is loaded as a Resource.

 

To upgrade from Melati 0.53.3 to Melati 0.53.4

 

To upgrade from Melati 0.53.2.1 to Melati 0.53.3

 

To upgrade from Melati 0.52 to Melati 0.53

 

To upgrade from Melati 0.50 to Melati 0.52

 

To upgrade from Melati Alpha Releases to Melati 0.50

As this is the 1st beta release, please follow the Installation instructions.

 

Documentation

Documentation for Melati can be found on the website, and on the Melati page at SourceForge. This README is just an overview.

The Java Doc API's, is included with this release.

We strongly recommend joining the Melati Users mailing list

If you are interested in contributing code to Melati, please also join the Melati Developers mailing list.

If you simply want to be kept up-to-date with announcements, please join the low traffic Melati Announcements mailing list.

If you are looking for support, found a bug, have a suggestion, or just want to chat with the developers, use the Melati developers or Melati Users mailing list.

 

Licensing

Melati is free software; Permission is granted to copy, distribute and/or modify this software under the terms either:

a) the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

or

b) any version of the Melati Software License.

 

The GNU General Public License version 2 is included in this snapshot, and is available online.

The Melati Software License is compatible with the Apache Software Foundation's Apache Software License. It is included in this snapshot , and is available online at http://melati.org.


Anatomy of this Release

 

Installation

This document describes how to install the system on a new machine.

Prerequisites

Hardware

Since Melati is written entirely in Java, it is portable relatively easily to any machine which supports the JVMs mentioned below.

Software

Melati has been proved to work in the following environments:

Operating System
  • Linux 2.4 with glibc 2.2, 2.2.12 with glibc 2.1.1, 2.0.34/i586 with glibc 2.0.7.
  • Win2000 | WinNT/i586
Web Server / Servlet Engine
  • Apache 1.3.12 / JServ 1.1 (Apache 1.3.14 / Tomcat 3.2.1 works but hasn't yet been used for a production deployment)
  • MS IIS 4.0 / Apache Tomcat 3.1
JDK

1.2, 1.3

JSDK
2.0, 2.2 (thanks to a slight hack you can run, and recompile, Melati against either version interchangeably), 2.3
Database
  • PostgreSQL 7.0 (and up)
  • MySQL
  • HSQLDB
  • McKoiDB
Template Engine
Webmacro 0.98p1 and up, Velocity 1.1 and up

The JDBC facilities used by Melati are pretty simple, and we are aiming for compatibility with any DBMS which supports JDBC and transactions, but for now Postgresql is what we use.

We expect Melati to run in most Servlet Environments (we just havn't tested them all yet :)

Step by step Installation

It is assumed that you already have a working installation of Webmacro (i.e. web server, servlet runner, and Webmacro classes), and a working installation of Postgres or, presuming compatibility, another RDBMS.

It is assumed you are installing from the Melati Package. If you would like to build melati yourself from the CVS sources, please use the installation doc available from http://melati.org.

1. Set up a database for use by Melati. With Postgres this involves typing, for example, createdb melatitest at the Linux prompt, as a user who is allowed to create databases.
2. Arrange for the user in whose name your httpd runs---often, `nobody'---to be able to connect to the test database and create tables in it. With Postgres this is a no-op under the default `security' setup, assuming that your postmaster is running on the same machine as your web server.
3. Download the latest Melati snapshot from www.melati.org, and unzip or untar it. eg:
  • Unix users type:
    • cd /usr/local/
    • tar -xzf melati_0.54.tar.gz
    • for convenience, create a soft link: ln -s melati_0.54 melati
  • Windows users should use WinZip
4.

Arrange for Melati's classes and properties files to be accessible to your servlet runner.

For Apache Jserv, this can be done either in the jserv.properties file, by adding a lines

wrapper.classpath=/usr/local/melati/lib/melati.jar
wrapper.classpath=/usr/local/melati/src/

or in your <zone>.properties file by adding 

/usr/local/melati/lib/melati.jar,/usr/local/melati/src/

to the line beginning repositories=

 
5.

Arrange for Melati's statically served pages to be accessible via your web server.

By default, Melati will expect to find its JavaScript, images and static HTML under http://your.server/melati-static. To set this up with Apache, one typically does something like 


ln -s /usr/local/melati/src/org/melati /usr/local/apache/htdocs/melati-static

An alternate URL can be specified in the configuration file src/org/melati/org.melati.MelatiServlet.properties.

6.

Set the path allowing your application to access the Melati templates. Melati looks for its templates relative to src/org/melati in its source tree, so you should edit your template path accordingly:

6.1 For Webmacro:

By default Webmacro will load templates from the CLASSPATH, so the easiest thing to do is add something like

wrapper.classpath=/usr/local/melati/src/org/melati/

to your ServletRunner's CLASSPATH. Alternatively, set the path in your WebMacro.properties file.

6.2 For Velocity

  1. in org.melati.MelatiServlet.properties, Specify Velocity as your Template Engine:
    org.melati.MelatiServlet.templateEngine=org.melati.template.velocity.VelocityTemplateEngine
  2. you should set your TemplatePath in org.melati.MelatiServlet.properties: org.melati.MelatiServlet.templatePath=/usr/local/packages/melati/org/melati/
7.

Edit Melati's database config file, found in the source tree as org/melati/org.melati.LogicalDatabase.properties, which describes the mapping from "logical database names" to JDBC connection details. You may not have to change anything.

If you wish, you can also edit org.melati.MelatiServlet.properties (in the same directory) to choose between a login mechanism based on servlet sessions (i.e. cookies, which is the default) and one based on HTTP Basic Authorization (commonly used for password-protecting static pages).
8. Restart your Servlet Runner, typically you will need to kick apache using apachectl restart.
9.

To check that Melati is working, try looking at 


http://localhost/<servlet zone>/org.melati.test.ConfigServletTest/

This is the 1st servlet in the Melati Test suite. the test suite demonstrates some of the features of melati, and gives you access to examples. It will also help you debug your installation. If you are asked to supply a username/password, please use _administrator_ / FIXME (and don't forget to change this before you launch your application).

 

Recompiling

If all the necessary libraries (see below) are in your classpath, you can recompile Melati so: 

cd src/org/melati
javac `find -name '*.java'`

For a typical installation using webmacro rather than Velocity or JTemplater, install our postgresql jar and try this: 

cd src/org/melati
rm -rf template/velocity template/jtemplater poem/odmg
javac `find -name '*.java'`

Thanks to Chris Kimptoc, there is also a build script for ANT in org/melati/build.

The code should compile cleanly with any compiler (jikes is very nice and fast!), except for complaints about "deprecated APIs", which arise from some classes implementing JSDK 2.0 methods now marked as @deprecated. If anything worse happens with your compiler we would like to know.

If you change Poem.dsd (you probably shouldn't), don't forget to rerun the DSD preprocessor: 

cd src/org/melati/poem
java org.melati.poem.prepro.DSD Poem.dsd
cd src/org/melati
javac `find -name '*.java'`

The full list of compilation dependencies is

You can obtain a bleeding edge snapshot of Melati by anonymous CVS. Make sure to join the melati-developers mailing list. With the standard Unix cvs client you need to do something like 

$ mkdir melati/src
$ cd melati/src
$ cvs -d :pserver:anonymous@melati.org:/usr/cvsroot login
(Logging in to anonymous@melati.org)
CVS password: anonymous
$ cvs -d :pserver:anonymous@melati.org:/usr/cvsroot checkout org/melati org/apache javax

Thereafter you will be able to get an updated snapshot by doing 

$ cd melati/src/org/melati
$ cvs update
(CVS remembers the server from which the tree came in the control files in the CVS subdirectories it creates, and the login/password you gave in a file .cvspass in your home directory.)

For a Windows CVS client, try www.wincvs.org. Point it at the repository /usr/cvsroot on melati.org, give username and password anonymous, and make sure to check out the modules org/melati, org/apache and javax.

If you are working over a slow link, you might find the rsync program useful; let us know if you would like "anonymous rsync" access.

 

Getting Started

For the time being, please read the Poem User Guide and Preprocessor User Guide on http://melati.org. You can also find a simple example application in /lib/example.zip. You can see this application working as part of the Melati Test suite:

http://localhost/<servlet zone>/org.melati.test.ConfigServlet/

Please ask for help on the mailing lists..

 

Credits

Melati it the 3rd iteration of similar software developed by Paneris (http://www.paneris.org), and was largely written by William Chesters.

The core developers are listed in the CREDITS file. If you would like to join the Melati Project you are more than welcome. Please join the Developers Mailing list. Anyone demonstrating reasonable ability will be granted write access to the CVS repository.