org.melati.servlet
Class PoemServlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          org.melati.servlet.ConfigServlet
              org.melati.servlet.PoemServlet

All Implemented Interfaces:

Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:

PoemServletTest, TemplateServlet

public abstract class PoemServlet
extends ConfigServlet

Base class to use Poem with Servlets.

Simply extend this class and override the doPoemRequest method. If you are going to use a template engine look at TemplateServlet.

• By default, the path info of the URL by which the servlet was called up is examined to determine the `logical name' of the Melati POEM database to which the servlet should connect, and possibly a table within that database, an object within that table, and a `method' to apply to that object. The URL is expected to take one of the following forms:

  http://h/s/db/
  http://h/s/db/meth
  http://h/s/db/tbl/meth
  http://h/s/db/tbl/troid/meth
  http://h/s/db/tbl/troid/meth/other

  and the following components are broken out of the path info and passed to your application code in the melati parameter (which is also copied automatically into context so that it is easily available in templates):

  h	host name, such as www.melati.org
  s	servlet-determining part, such as melati/org.melati.admin.Admin
  db	The first element of the path info is taken to be the `logical name' of the Melati 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.
  tbl	The DBMS name of a table with which the servlet is concerned: 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 tbl with which the servlet is concerned: perhaps it is meant to display it. This is automatically made available in templates as $melati.Object.
  meth	A freeform string telling your servlet what it is meant to do. This is automatically made available in templates as $melati.Method.
  other	Any other information you wish to put in the pathinfo. This is useful, for instance, if you wish to specify the "filename" of your servlet. For instance, if you call /db/myfiles/0/Download/afile.html and return a stream with a content-type of application/octet-stream most browsers will prompt you to save the "file" as afile.html

• You can change the way these things are determined by overriding poemContext.
• Any POEM database operations you perform will be done with the access rights of the POEM User associated with the servlet session. If there is no established servlet 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's possible to configure how your PoemServlet-derived servlets implement user login. If the properties file org.melati.MelatiConfig.properties exists and contains a setting org.melati.MelatiConfig.accessHandler=foo, then foo is taken to be the name of a class implementing the AccessHandler interface. The default is HttpSessionAccessHandler, which stores the user id in the servlet session, and redirects to the Login servlet to throw up templated login screens. If instead you specify HttpBasicAuthenticationAccessHandler, the user id is maintained using HTTP Basic Authentication (RFC2068 11.1, the mechanism commonly used to password-protect static pages), and the task of popping up login dialogs is delegated to the browser. The advantage of the former method is that the user gets a more informative interface which is more under the designer's control; the advantage of the latter method is that no cookies or URL rewriting are required---for instance it is probably more appropriate for WAP phones. Both methods involve sending the user's password in plain text across the public network.

See Also:

Database.guestAccessToken(), PoemThread.commit(), PoemThread.rollback(), poemContext(org.melati.Melati), AccessHandler, HttpSessionAccessHandler, Login, HttpBasicAuthenticationAccessHandler, Serialized Form

Field Summary

Fields inherited from class org.melati.servlet.ConfigServlet

melatiConfig, sysAdminEmail, sysAdminName

Constructor Summary

PoemServlet()

Method Summary

protected void	_handleException(Melati melati, Exception exception)
void	destroy()
protected void	doConfiguredRequest(Melati melati) Process the request.
protected abstract void	doPoemRequest(Melati melati) Override this method to build up your own output.
String	getSysAdminEmail() Override this to provide a different administrator's details to the database admin user.
String	getSysAdminName() Override this to provide a different administrator's details to the database admin user.
protected void	handleException(Melati melati, Exception exception) Default method to handle an exception without a template engine.
protected PoemContext	poemContext(Melati melati)
protected PoemContext	poemContextWithLDB(Melati melati, String logicalDatabase)
protected void	prePoemSession(Melati melati) A place to do things before entering the session of the user, here is a good place to use root access token.

Methods inherited from class org.melati.servlet.ConfigServlet

doGet, doPost, error, httpStatusCode, init, melatiConfig, setSysAdminEmail, setSysAdminName, writeConnectionPendingException, writeError

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service

Methods inherited from class javax.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class java.lang.Object

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

Constructor Detail

PoemServlet

public PoemServlet()

Method Detail

prePoemSession

protected void prePoemSession(Melati melati)
                       throws Exception

A place to do things before entering the session of the user, here is a good place to use root access token. Overriden in TemplateServlet.

Parameters:

melati - org.melati.Melati A source of information about the Melati database context (database, table, object) and utility objects such as error handlers.

Throws:

Exception

destroy

public void destroy()

Specified by:

destroy in interface javax.servlet.Servlet

Overrides:

destroy in class javax.servlet.GenericServlet

See Also:

Servlet.destroy()

doConfiguredRequest

protected void doConfiguredRequest(Melati melati)
                            throws javax.servlet.ServletException,
                                   IOException

Process the request.

Specified by:

doConfiguredRequest in class ConfigServlet

Throws:

javax.servlet.ServletException

IOException

getSysAdminName

public String getSysAdminName()

Override this to provide a different administrator's details to the database admin user.

Overrides:

getSysAdminName in class ConfigServlet

Returns:

the System Administrators name.

getSysAdminEmail

public String getSysAdminEmail()

Override this to provide a different administrator's details to the database admin user.

Overrides:

getSysAdminEmail in class ConfigServlet

Returns:

the System Administrators email address.

handleException

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

Default method to handle an exception without a template engine.

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 PathInfoException

Overrides:

poemContext in class ConfigServlet

Throws:

PathInfoException

poemContextWithLDB

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

Throws:

PathInfoException

doPoemRequest

protected abstract void doPoemRequest(Melati melati)
                               throws Exception

Override this method to build up your own output.

Parameters:

melati -

Throws:

Exception