org.melati.app
Class AbstractPoemApp

java.lang.Object
  org.melati.app.AbstractConfigApp
      org.melati.app.AbstractPoemApp

All Implemented Interfaces:

App

Direct Known Subclasses:

AbstractTemplateApp, PoemApp

public abstract class AbstractPoemApp
extends AbstractConfigApp
implements App

Base class to use Poem as an application.

Simply extend this class and override the doPoemRequest(org.melati.Melati) method. If you are going to use a template engine look at AbstractTemplateApp.

• The command line arguments are expected in the following order:

  
  db
  db method
  db table method
  db table troid method

  these components are broken out of the command line arguments and passed to your application code in the Melati parameter.

  db	The first argument is taken to be the `logical name' of the POEM database to which the servlet should connect. It is mapped onto JDBC connection details via the config file org.melati.LogicalDatabase.properties, of which there is an example in the source tree. This is automatically made available in templates as $melati.Database.
  table	The name of a table to work on: perhaps it is meant to list its contents. This is automatically made available in templates as $melati.Table.
  troid	The POEM `troid' (table row identifier, or row-unique integer) of a row within a table. This is automatically made available in templates as $melati.Object.
  method	A freeform string telling your servlet what it is meant to do. This is automatically made available in templates as $melati.Method.

• You can change the way these things are determined by overriding poemContext(org.melati.Melati).
• Any POEM database operations you perform will be done with the access rights of the POEM User associated with the POEM session. If there is no established session, the current user will be set to the default `guest' user. If this method terminates with an AccessPoemException, indicating that you have attempted something which you aren't entitled to do, the user will be prompted to log in, and the original request will be retried. The precise mechanism used for login is configurable.
• No changes made to the database by other concurrently executing threads will be visible to you (in the sense that once you have seen a particular version of a record, you will always subsequently see the same one), and your own changes will not be made permanent until this method completes successfully or you perform an explicit PoemThread.commit(). If it terminates with an exception or you issue a PoemThread.rollback(), your changes will be lost.
• It is possible to configure how your PoemApp-derived applications implement user login. If the properties file org.melati.MelatiApp.properties exists and contains a setting org.melati.MelatiApp.accessHandler=foo, then foo is taken to be the name of a class implementing the AccessHandler interface.

If you do not need access handling then set your accessHandler to org.melati.login.OpenAccessHandler. If you do need access handling then set your accessHandler to org.melati.login.CommandLineAccessHandler. However this is not extremely secure, as the user could potentially change this seting to OpenAccessHandler as they are on the same machine. You can specify the username and password to use by adding command line parameters:

 -username user -password password
 

See Also:

Database.guestAccessToken(), PoemThread.commit(), PoemThread.rollback(), poemContext(org.melati.Melati), AccessHandler, HttpSessionAccessHandler, Login, OpenAccessHandler, CommandLineAccessHandler

Field Summary

Fields inherited from class org.melati.app.AbstractConfigApp

melatiConfig, output

Constructor Summary

AbstractPoemApp()

Method Summary

protected void	_handleException(Melati melati, Exception exception)
protected void	doConfiguredRequest(Melati melati) Instantiate this method to build up your own output.
protected abstract void	doPoemRequest(Melati melati) Override this method to do your own thing.
protected static void	handleException(Melati melati, Exception exception) Default method to handle an exception.
Melati	init(String[] args) Initialise.
protected PoemContext	poemContext(Melati melati) Set up the (@link PoemContext}, but only the Method.
protected PoemContext	poemContextWithLDB(Melati melati, String logicalDatabase) This is provided for convenience, so you don't have to specify the logical database in the arguments.
protected void	prePoemSession(Melati melati) A place holder for things you might want to do before setting up a PoemSession.
protected void	setTableTroidMethod(PoemContext pc, String[] args)
void	term(Melati melati) Clean up at end of run.

Methods inherited from class org.melati.app.AbstractConfigApp

applyNamedArguments, getSysAdminEmail, getSysAdminName, melatiConfig, run, setOutput

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.melati.app.App

run, setOutput

Constructor Detail

AbstractPoemApp

public AbstractPoemApp()

Method Detail

init

public Melati init(String[] args)
            throws MelatiException

Initialise.

Overrides:

init in class AbstractConfigApp

Parameters:

args - the command line arguments

Returns:

a configured Melati a newly created Melati

Throws:

MelatiException - if something goes wrong during initialisation

See Also:

AbstractConfigApp.init(java.lang.String[])

term

public void term(Melati melati)
          throws IOException

Clean up at end of run.

Overrides:

term in class AbstractConfigApp

Parameters:

melati - the melati

Throws:

IOException

prePoemSession

protected void prePoemSession(Melati melati)
                       throws Exception

A place holder for things you might want to do before setting up a PoemSession.

Parameters:

melati - the current Melati

Throws:

Exception - if anything goes wrong

doConfiguredRequest

protected void doConfiguredRequest(Melati melati)

Description copied from class: AbstractConfigApp

Instantiate this method to build up your own output.

Specified by:

doConfiguredRequest in class AbstractConfigApp

Parameters:

melati - a configured Melati

handleException

protected static void handleException(Melati melati,
                                      Exception exception)
                               throws Exception

Default method to handle an exception.

Parameters:

melati - the Melati

exception - the exception to handle

Throws:

Exception

_handleException

protected final void _handleException(Melati melati,
                                      Exception exception)
                               throws Exception

Throws:

Exception

poemContext

protected PoemContext poemContext(Melati melati)
                           throws InvalidArgumentsException

Description copied from class: AbstractConfigApp

Set up the (@link PoemContext}, but only the Method.

Overrides:

poemContext in class AbstractConfigApp

Parameters:

melati - the current Melati

Returns:

a partially configured PoemContext

Throws:

InvalidArgumentsException

setTableTroidMethod

protected void setTableTroidMethod(PoemContext pc,
                                   String[] args)

poemContextWithLDB

protected PoemContext poemContextWithLDB(Melati melati,
                                         String logicalDatabase)
                                  throws InvalidArgumentsException

This is provided for convenience, so you don't have to specify the logical database in the arguments. This is useful when writing applications where you are only accessing a single database. Simply override poemContext(Melati melati) thus:

 protected PoemContext poemContext(Melati melati) 
     throws InvalidArgumentsException {
   return poemContextWithLDB(melati,"");
 }
 

Throws:

InvalidArgumentsException

doPoemRequest

protected abstract void doPoemRequest(Melati melati)
                               throws Exception

Override this method to do your own thing.

Parameters:

melati - a Melati containing POEM and other configuration data

Throws:

Exception