Melati Readme Documentation

> # The Melati Project

> ### Tim Pizey

> #### Last change $Date: 2010/02/13 10:42:28 $, by $Author: timp $ At melati.org

> #### Contents:

> - About Melati
> - Release Notes
> - Upgrading
> - Documentation
> - Licensing
> - Anatomy of this Release
> - Installing
> - Recompiling
> - Getting Started
> - Credits

> ## About Melati

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

> - a generic database admin system, allowing the site manager to edit both the contents and the structure of the database through a simple web based interface.
> - an object layer where the database is seen as a collection of Java objects, via a (genuinely!) easy-to-use transparent persistence layer on top of JDBC.
> - a low level security model allowing restrictions to be placed on tables, rows and fields.
> - cookie-based or HTTP-based login provoked automatically by access control failure.
> - rapid templating mechanism, using "templets" (sub-templates) for rendering interface elements (e.g. HTML input boxes, dropdowns), and providing an easy interface with persistent objects.
> - close integration with Webmacro and Velocity template engines.
> - built in file upload

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

> - Integration with Maven 1 and 2
> - WebMacro templates bundled and readable from within the .jar
> - Support for SQLServer, MySQL, MckoiDB, HSQLDB, MSSQL, Oracle
> - Support for JSDK 2.0, 2.1, 2.2, 2.3 (Tomcat)
> - Support for Velocity
> - DSDs can now be imported into other DSDs
> - Support for Webmacro 1.1
> - Cascading deletion in POEM
> - Cleaner servlet API
> - File upload
> - 'Remember me' feature for login.
> - Melati Test suite
> - Now available as a downloadable zip / tar.gz.
> - Precompiled (javac) melati.jar
> - Ant build script
> - Mailing list hosted on SourceForge
> - More documentation.
> - Support for Eclipse
> - Maven validation and site generation
> - Dual ASF / GPL licensing.
> - Poem no longer intertwined with Melati
> - Poem Preprocessor now a Maven plugin
> - Templets loacated in the same direcory, regardless of template engine

> ## Upgrading

> ### 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 `ensure`d 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

> - you must install the 0.95b3 webmacro snapshot

> ###

> ### To upgrade from Melati 0.53.2.1 to Melati 0.53.3

> - you must install the 2000-12-06 webmacro snapshot

> ### To upgrade from Melati 0.52 to Melati 0.53

> - you must install version 0.94 (at least) of webmacro
> - if your code overrides `Persistent.deleteAndCommit(), please read the Release Notes.

> ###

> ### To upgrade from Melati 0.50 to Melati 0.52

> - your Webmacro based servlets should now extend org.melati.template.webmacro.WebmacroTemplateServlet, and return a String represtation of the Template name, not the actual template.
> - If you override any templets, they will need to move to the /template/webmacro/templets directory.

> - You will need to add the following line to`org.melati.Melatiservlet.properties`

>   `org.melati.MelatiServlet.templateEngine=org.melati.template.webmacro.WebmacroTemplateEngine`

>   Also, if you have an entry for TempletLoader, it should now read:

>   `org.melati.MelatiServlet.templetLoader=org.melati.template.ClassNameTempletLoader`

>   And javascriptLibraryURL should read

>   `org.melati.MelatiServlet.javascriptLibraryURL=/melati-static/template/webmacro/templets/html`

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

> - Melati Website
> - Melati SourceForge Page

> 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

> - /doc - contains the API documentation
> - /lib - contains melati.jar, compiled using JDK 1.2 JAVAC
> - /src - contains the melati sources (in src.zip), and additional files (*.wm, *.html, *.gif and *.js) in the org/melati/* tree.

> ## 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 in `org.melati.MelatiServlet.properties`, Specify Velocity as your Template Engine: `org.melati.MelatiServlet.templateEngine=org.melati.template.velocity.VelocityTemplateEngine` 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

> - `src/` from the Melati distribution, not only for `org.melati`... but also for a couple of utility classes in `org.apache.java.lang` and a stub in `javax.servlet` (enabling us to compile and run interchangeably against JSDK 2.0 and 2.2)

> - The Servlet Development Kit (JSDK) 2.0 or 2.2, generally `jsdk.jar`. Melati will compile and run against either version.

> - The webmacro template engine, e.g. `webmacro.jar` from the appropriate distribution. You need this even if you intend to use Velocity, because of the Velocity-Webmacro compatibility mode.

> - The Velocity template engine, e.g. `velocity-#.jar` from the appropriate distribution.

>   If you do not intend to use Velocity, you can just delete `org/melati/template/velocity/` from the Melati source tree.

> - The JTemplater template engine.

>   If you do not intend to use JTemplater (you probably don't), you can just delete `org/melati/template/jtemplater/` from the Melati source tree.

> - The Postgresql JDBC driver, e.g. `org/melati/poem/postgresql/required-libs/postgresql-7.0-fixedTimestampAndReceiveString.jar`, or `postgresql.jar` from the appropriate distribution. The former has some performance fixes which greatly reduce the time taken for Melati to start up, as well as fixes to the way "`TIMESTAMP`" fields are marshalled which may be required under some circumstances.

>   If you do not intend to use Postgresql, you can just delete `org/melati/poem/postgresql` and `org/melati/poem/dbms/Postgresql.java` from the Melati source tree.

> - The ODMG library included in the Melati sources as `org/melati/poem/odmg/required-libs/odmg3.jar`.

>   If you do not intend to use the ODMG interface, you can just delete `org/melati/poem/odmg` from the Melati source tree.

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