org.melati
Class Melati

java.lang.Object
  org.melati.Melati

public class Melati
extends Object

This is the main entry point for using the Melati framework. A Melati exists once per request, or command from an application.

It provides a central container for all the relevant objects that a Servlet or command line application needs to create textual output, optionally using a Template Engine or a Database.

You will need to create a MelatiConfig in order to construct a Melati.

If you are using servlets, you will want to construct a Melati with a request and response object. Otherwise, simply pass in a Writer.

If you are using a template engine outside of a servlets context you will still need the servlets jar in your classpath, annoyingly, as Velocity and WebMacro introspect all possible methods and throw a ClassNotFound exception if the servlets classes are not available.

Melati is typically used with Servlets, POEM (Persistent Object Engine for Melati) and a Template Engine

See Also:

MelatiConfig, ConfigServlet, PoemServlet, TemplateServlet

Field Summary

protected String	contentType
static String	DEFAULT_ENCODING UTF-8.
protected String	responseCharset Suggested character encoding for use in responses.

Constructor Summary

Melati(MelatiConfig config, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Construct a Melati for use with Servlets.

Melati(MelatiConfig config, MelatiWriter writer)
Construct a Melati for use in 'stand alone' mode.

Method Summary

void	establishCharsets() Suggest a response character encoding and if necessary choose a request encoding.
String[]	getArguments() Get the Arguments array.
MelatiConfig	getConfig() Get the MelatiConfig associated with this Request.
String	getContentType()
Object	getContextUtil(String className) Get a named context utility eg org.melati.admin.AdminUtils.
Database	getDatabase() Get the POEM Database for this Request.
String	getDatabaseName()
String	getEncoding() Return the encoding that is used for writing.
HTMLMarkupLanguage	getHTMLMarkupLanguage() Get a HTMLMarkupLanguage.
Object	getInstance(String className) Get a named context utility eg org.melati.admin.AdminUtils.
String	getJavascriptLibraryURL() Get the URL for the JavascriptLibrary.
Vector<String>	getKnownDatabaseNames() Return the names of other databases known at the moment.
String	getLoginURL() Get the URL for the Login Page.
String	getLogoutURL() Get the URL for the Logout Page.
MarkupLanguage	getMarkupLanguage() Get a MarkupLanguage for use generating output from templates.
String	getMethod() Get the Method (if any) that has been set for this Request.
Persistent	getObject() Get the POEM Object (if any) in use for this Request.
String[]	getPathInfoParts() Get the PathInfo for this Request split into Parts by '/'.
PoemContext	getPoemContext() Get the PoemContext for this Request.
PoemLocale	getPoemLocale() Returns a PoemLocale object based on the Accept-Language header of this request.
String	getRelativeZoneURL()
javax.servlet.http.HttpServletRequest	getRequest() Get the servlet request object.
javax.servlet.http.HttpServletResponse	getResponse() Get the servlet response object.
String	getSameURL() The URL of the servlet request associated with this Melati.
ServletTemplateContext	getServletTemplateContext() Get the TemplateContext used for this Request.
String	getServletURL() Get the URL for this request.
javax.servlet.http.HttpSession	getSession() Get the Session for this Request.
MelatiWriter	getStringWriter() Get a StringWriter.
Table	getTable() Get the POEM Table (if any) in use for this Request.
TemplateContext	getTemplateContext() Get the TemplateContext used for this Request.
TemplateEngine	getTemplateEngine() Get the template engine in use for this Request.
String	getURLQueryEncoding() Return the encoding that is used for URL encoded query strings.
User	getUser() Get a User for this request (if they are logged in).
MelatiWriter	getWriter() Get a Writer for this request.
String	getZoneURL() Get the URL for this Servlet Zone.
boolean	isReferencePoemType(Field field) Establish if field is a ReferencePoemType field.
void	loadTableAndObject() Load a POEM Table and POEM Object for use in this request.
String	sameURLWith(String field) The URL of the servlet request associated with this Melati, with a modified or added form flag setting (query string component).
String	sameURLWith(String field, String value) The URL of the servlet request associated with this Melati, with a modified or added form parameter setting (query string component).
void	setArguments(String[] args) Set the aruments array from the commandline.
void	setBufferingOff() Turn off buffering of the output stream.
void	setFlushingOn() Turn on flushing of the output stream.
void	setMarkupLanguage(MarkupLanguage ml) Use this method if you wish to use a different MarkupLanguage, WMLMarkupLanguage for example.
void	setPassbackExceptionHandling() This allows an Exception to be handled inline during Template expansion for example, if you would like to render AccessPoemExceptions to a String to be displayed on the page that is returned to the client.
void	setPoemContext(PoemContext context) Set the PoemContext for this request.
void	setPropagateExceptionHandling() The normal state of affairs: an exception is thrown and it is handled by the servlet.
void	setRequest(javax.servlet.http.HttpServletRequest request) It is sometimes convenient to reconstruct the request object and reset it, for example when returning from a log-in page.
void	setResponse(javax.servlet.http.HttpServletResponse response) Used to set response mock in tests.
void	setResponseContentType(String type) Sets the content type for use in the response.
void	setTemplateContext(TemplateContext tc) Set the TemplateContext to be used for this Request.
void	setTemplateEngine(TemplateEngine te) Set the template engine to be used for this Request.
void	setWriter(MelatiWriter writerP)
String	templateName(String key) Find a db specific template if it exists, otherwise a non-specific one, searching through all template paths.
String	urlEncode(String string)
void	write() Write the buffered output to the Writer we also need to stop the flusher if it has started.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING

UTF-8.

See Also:

Constant Field Values

responseCharset

protected String responseCharset

Suggested character encoding for use in responses.

contentType

protected String contentType

Constructor Detail

Melati

public Melati(MelatiConfig config,
              javax.servlet.http.HttpServletRequest request,
              javax.servlet.http.HttpServletResponse response)

Construct a Melati for use with Servlets.

Parameters:

config - - the MelatiConfig

request - - the Servlet Request

response - - the Servlet Response

Melati

public Melati(MelatiConfig config,
              MelatiWriter writer)

Construct a Melati for use in 'stand alone' mode. NB: you will not have access to servlet related stuff (eg sessions)

Parameters:

config - - the MelatiConfig

writer - - the Writer that all output is written to

Method Detail

getRequest

public javax.servlet.http.HttpServletRequest getRequest()

Get the servlet request object.

Returns:

the Servlet Request

setRequest

public void setRequest(javax.servlet.http.HttpServletRequest request)

It is sometimes convenient to reconstruct the request object and reset it, for example when returning from a log-in page.

Parameters:

request - - new request object

See Also:

HttpSessionAccessHandler

setResponse

public void setResponse(javax.servlet.http.HttpServletResponse response)

Used to set response mock in tests.

Parameters:

response - - mock response object

See Also:

HttpSessionAccessHandler

getResponse

public javax.servlet.http.HttpServletResponse getResponse()

Get the servlet response object.

Returns:

- the Servlet Response

setPoemContext

public void setPoemContext(PoemContext context)
                    throws DatabaseInitException

Set the PoemContext for this request. If the Context has a LogicalDatabase set, this will be used to establish a connection to the database.

Parameters:

context - - a PoemContext

Throws:

DatabaseInitException - - if the database fails to initialise for some reason

See Also:

LogicalDatabase, PoemServlet

loadTableAndObject

public void loadTableAndObject()

Load a POEM Table and POEM Object for use in this request. This is useful as often Servlet requests are relevant for a single Table and/or Object. The Table name and Object id are set from the PoemContext.

See Also:

Admin, PoemServlet

getPoemContext

public PoemContext getPoemContext()

Get the PoemContext for this Request.

Returns:

- the PoemContext for this Request

getDatabase

public Database getDatabase()

Get the POEM Database for this Request.

Returns:

- the POEM Database for this Request

See Also:

setPoemContext(org.melati.PoemContext)

getDatabaseName

public String getDatabaseName()

Returns:

the name of the Database

getKnownDatabaseNames

public Vector<String> getKnownDatabaseNames()

Return the names of other databases known at the moment.

Returns:

a Vector of database names

getTable

public Table getTable()

Get the POEM Table (if any) in use for this Request.

Returns:

the POEM Table for this Request

See Also:

loadTableAndObject()

getObject

public Persistent getObject()

Get the POEM Object (if any) in use for this Request.

Returns:

the POEM Object for this Request

See Also:

loadTableAndObject()

getMethod

public String getMethod()

Get the Method (if any) that has been set for this Request.

Returns:

the Method for this Request

See Also:

PoemContext, ConfigServlet.poemContext(org.melati.Melati), PoemServlet.poemContext(org.melati.Melati)

setTemplateEngine

public void setTemplateEngine(TemplateEngine te)

Set the template engine to be used for this Request.

Parameters:

te - - the template engine to be used

See Also:

TemplateServlet

getTemplateEngine

public TemplateEngine getTemplateEngine()

Get the template engine in use for this Request.

Returns:

- the template engine to be used

setTemplateContext

public void setTemplateContext(TemplateContext tc)

Set the TemplateContext to be used for this Request.

Parameters:

tc - - the template context to be used

See Also:

TemplateServlet

getTemplateContext

public TemplateContext getTemplateContext()

Get the TemplateContext used for this Request.

Returns:

- the template context being used

getServletTemplateContext

public ServletTemplateContext getServletTemplateContext()

Get the TemplateContext used for this Request.

Returns:

- the template context being used

getConfig

public MelatiConfig getConfig()

Get the MelatiConfig associated with this Request.

Returns:

- the configuration being used

getPathInfoParts

public String[] getPathInfoParts()

Get the PathInfo for this Request split into Parts by '/'.

Returns:

- an array of the parts found on the PathInfo

setArguments

public void setArguments(String[] args)

Set the aruments array from the commandline.

Parameters:

args -

getArguments

public String[] getArguments()

Get the Arguments array.

Returns:

the arguments array

getSession

public javax.servlet.http.HttpSession getSession()

Get the Session for this Request.

Returns:

- the Session for this Request

getContextUtil

public Object getContextUtil(String className)

Get a named context utility eg org.melati.admin.AdminUtils.

Parameters:

className - Name of a class with a single argument Melati constructor

Returns:

the instantiated class

getInstance

public Object getInstance(String className)

Get a named context utility eg org.melati.admin.AdminUtils.

Parameters:

className - Name of a class with a single argument Melati constructor

Returns:

the instantiated class

getLogoutURL

public String getLogoutURL()

Get the URL for the Logout Page.

Returns:

- the URL for the Logout Page

See Also:

Logout

getLoginURL

public String getLoginURL()

Get the URL for the Login Page.

Returns:

- the URL for the Login Page

See Also:

Login

getZoneURL

public String getZoneURL()

Get the URL for this Servlet Zone.

Returns:

- the URL for this Servlet Zone

See Also:

HttpUtil.zoneURL(javax.servlet.http.HttpServletRequest)

getRelativeZoneURL

public String getRelativeZoneURL()

Returns:

the relative url for the Servlet Zone of the current request

getServletURL

public String getServletURL()

Get the URL for this request. Not used in Melati.

Returns:

- the URL for this request

See Also:

HttpUtil.servletURL(javax.servlet.http.HttpServletRequest)

getJavascriptLibraryURL

public String getJavascriptLibraryURL()

Get the URL for the JavascriptLibrary. Convenience method.

Returns:

- the URL for the JavascriptLibrary

See Also:

MelatiConfig.getJavascriptLibraryURL()

getPoemLocale

public PoemLocale getPoemLocale()

Returns a PoemLocale object based on the Accept-Language header of this request. If no usable Accept-Language header is found or we are using Melati outside of a servlet context then the configured default locale is returned.

Returns:

a PoemLocale object

establishCharsets

public void establishCharsets()
                       throws CharsetException

Suggest a response character encoding and if necessary choose a request encoding.

If the request encoding is provided then we choose a response encoding to meet our preferences on the assumption that the client will also indicate next time what its request encoding is. The result can optionally be set in code or possibly in templates using setResponseContentType(String).

Otherwise we tread carefully. We assume that the encoding is the first supported encoding of the client's preferences for responses, as indicated by Accept-Charsets, and avoid giving it any reason to change.

Actually, the server preference is a bit dodgy for the response because if it does persuade the client to change encodings and future requests include query strings that we are providing now then we may end up with the query strings being automatically decoded using the wrong encoding by request.getParameter(). But by the time we end up with values in such parameters the client and server will probably have settled on particular encodings.

Throws:

CharsetException

setResponseContentType

public void setResponseContentType(String type)

Sets the content type for use in the response.

Use of this method is optional and only makes sense in a Servlet context. If the response is null then this is a no-op.

If the type starts with "text/" and does not contain a semicolon and a good response character set has been established based on the request Accept-Charset header and server preferences, then this and semicolon separator are automatically appended to the type.

Whether this function should be called at all may depend on the application and templates.

It should be called before any calls to getEncoding() and before writing the response.

See Also:

establishCharsets()

getContentType

public String getContentType()

Returns:

the contentType

setMarkupLanguage

public void setMarkupLanguage(MarkupLanguage ml)

Use this method if you wish to use a different MarkupLanguage, WMLMarkupLanguage for example. Cannot be set in MelatiConfig as does not have a noarg constructor.

Parameters:

ml - The ml to set.

getMarkupLanguage

public MarkupLanguage getMarkupLanguage()

Get a MarkupLanguage for use generating output from templates. Defaults to HTMLMarkupLanguage.

Returns:

- a MarkupLanguage, defaulting to HTMLMarkupLanguage

See Also:

TempletLoader, PoemLocale

getHTMLMarkupLanguage

public HTMLMarkupLanguage getHTMLMarkupLanguage()

Get a HTMLMarkupLanguage. Retained for backward compatibility as there are a lot of uses in templates.

Returns:

- a HTMLMarkupLanguage

sameURLWith

public String sameURLWith(String field,
                          String value)

The URL of the servlet request associated with this Melati, with a modified or added form parameter setting (query string component).

Parameters:

field - The name of the form parameter

value - The new value for the parameter (unencoded)

Returns:

The request URL with field=value. If there is already a binding for field in the query string it is replaced, not duplicated. If there is no query string, one is added.

See Also:

Form

sameURLWith

public String sameURLWith(String field)

The URL of the servlet request associated with this Melati, with a modified or added form flag setting (query string component).

Parameters:

field - The name of the form parameter

Returns:

The request URL with field=1. If there is already a binding for field in the query string it is replaced, not duplicated. If there is no query string, one is added.

See Also:

Form

getSameURL

public String getSameURL()

The URL of the servlet request associated with this Melati.

Returns:

a string

setBufferingOff

public void setBufferingOff()
                     throws IOException

Turn off buffering of the output stream. By default, melati will buffer the output, which will not be written to the output stream until you call melati.write(); Buffering allows us to catch AccessPoemExceptions and redirect the user to the login page. This could not be done if any bytes had already been written to the client.

Throws:

IOException - if a writer has already been selected

See Also:

FlushingServletTest

setFlushingOn

public void setFlushingOn()
                   throws IOException

Turn on flushing of the output stream.

Throws:

IOException - if there is a problem with the writer

getURLQueryEncoding

public String getURLQueryEncoding()

Return the encoding that is used for URL encoded query strings.

The requirement here is that parameters can be encoded in query strings included in URLs in the body of responses. User interaction may result in subsequent requests with such a URL. The HTML spec. describes encoding of non-alphanumeric ASCII using % and ASCII hex codes and, in the case of forms. says the client may use the response encoding by default. Sun's javadoc for java.net.URLEncoder recommends UTF-8 but the default is the Java platform encoding. Most significantly perhaps, org.mortbay.http.HttpRequest uses the request encoding. We should check that this is correct in the servlet specs.

So we assume that the servlet runner may dictate the encoding that will work for multi-national characters in field values encoded in URL's (but not necessarily forms).

If the request encoding is used then we have to try and predict it. It will be the same for a session unless a client has some reason to change it. E.g. if we respond to a request in a different encoding and the client is influenced. (See establishCharsets(). But that is only a problem if the first or second request in a session includes field values encoded in the URL and user options include manually entering the same in a form or changing their browser configuration. Or we can change the server configuration.

It would be better if we had control over what encoding the servlet runner used to decode parameters. Perhaps one day we will.

So this method implements the current policy and currently returns the current request encoding. It assumes establishCharsets() has been called to set the request encoding if necessary.

Returns:

the character encoding

See Also:

see also org.melati.admin.Admin#selection(ServletTemplateContext, Melati)

urlEncode

public String urlEncode(String string)

Parameters:

string - the String to encode

Returns:

the encoded string

getEncoding

public String getEncoding()

Return the encoding that is used for writing.

This should always return an encoding and it should be the same for duration of use of an instance.

Returns:

Response encoding or a default in stand alone mode

See Also:

setResponseContentType(String)

getWriter

public MelatiWriter getWriter()

Get a Writer for this request. If you have not accessed the Writer, it is reasonable to assume that nothing has been written to the output stream.

Returns:

- one of: - the Writer that was used to construct the Melati - the Writer associated with the Servlet Response - a buffered Writer - a ThrowingPrintWriter

setWriter

public void setWriter(MelatiWriter writerP)

Parameters:

writerP - the MelatiWriter to set

getStringWriter

public MelatiWriter getStringWriter()

Get a StringWriter.

Returns:

- one of: - a MelatiStringWriter from the template engine - a new MelatiStringWriter if template engine not set

write

public void write()

Write the buffered output to the Writer we also need to stop the flusher if it has started.

setPassbackExceptionHandling

public void setPassbackExceptionHandling()

This allows an Exception to be handled inline during Template expansion for example, if you would like to render AccessPoemExceptions to a String to be displayed on the page that is returned to the client.

See Also:

MarkupLanguage.rendered(Object), TailoredQuery

setPropagateExceptionHandling

public void setPropagateExceptionHandling()

The normal state of affairs: an exception is thrown and it is handled by the servlet.

getUser

public User getUser()

Get a User for this request (if they are logged in). NOTE POEM studiously assumes there isn't necessarily a user, only an AccessToken

Returns:

- a User for this request

isReferencePoemType

public boolean isReferencePoemType(Field field)

Establish if field is a ReferencePoemType field.

Parameters:

field - the field to check

Returns:

whether it is a reference poem type

templateName

public String templateName(String key)

Find a db specific template if it exists, otherwise a non-specific one, searching through all template paths.

Parameters:

key - fileName of template, without extension

Returns:

full resource name