com.samskivert.velocity
Class Application

java.lang.Object
  com.samskivert.velocity.Application

public class Application
extends Object

The servlet API defines the concept of a web application and associates certain attributes with it like document root and so on. This application class extends that concept by providing a base class that represents the web application. The application class is responsible for initializing services that will be used by the application's logic objects as well as cleaning them up when the application is shut down.

Error handling
The application provides a common error handling mechanism. The design is to catch any exceptions thrown by the logic and to convert them into friendly error messages that are inserted into the invocation context with the key "error" for easy display in the resulting web page.

The default process of mapping exceptions to friendly error messages is done using the ExceptionMap class. This can be replaced by overriding handleException(javax.servlet.http.HttpServletRequest, com.samskivert.velocity.Logic, java.lang.Exception).

Field Summary

protected javax.servlet.ServletContext	_context A reference to the servlet context in which this application is operating.
protected String	_logicPkg The prefix that we use to generate fully qualified logic class names.
protected MessageManager	_msgmgr A reference to our message manager or null if we have none.
protected SiteIdentifier	_siteIdent A reference to our site identifier.
protected SiteResourceLoader	_siteLoader Provides access to site-specific resources.
protected static String	MESSAGE_BUNDLE_PATH_KEY The servlet parameter key specifying the path to the application's translated message resources.
protected static String	SITE_JAR_PATH_KEY The servlet parameter key specifying the path to the site-specific jar files.
protected static String	SITE_MESSAGE_BUNDLE_PATH_KEY The servlet parameter key specifying the path to the site-specific translated message resources.
static String	VELOCITY_ATTR_KEY An initialized application automatically registers itself as a Velocity application attribute so that it can be retrieved by Velocity plugins using getApplicationAttribute(VELOCITY_ATTR_KEY).

Constructor Summary

Application()

Method Summary

protected void	checkAccess(InvocationContext ctx) Allows derived application classes to check access in a single location prior to resolving and dispatching a logic class, if they desire access control at this level.
protected void	configureVelocity(javax.servlet.ServletConfig config, Properties props) Called prior to initializing Velocity to allow the application to specify custom configuration properties.
protected MessageManager	createMessageManager(String bundlePath) Creates the message manager to be used for this application.
protected SiteIdentifier	createSiteIdentifier(javax.servlet.ServletContext ctx) Called to instantiate the site identifier that we'd like to use in this application.
protected void	didInit(javax.servlet.ServletConfig config) This should be overridden by the application implementation to invoke any necessary post-initialization code.
protected String	generateClass(String path) Given the servlet path (the part of the URI after the context path) this generates the classname of the logic class that should handle the request.
protected String	getInitParameter(javax.servlet.ServletConfig config, String key) Looks up an initialization parameter for this application.
MessageManager	getMessageManager() Returns the message manager in effect for this application, if one is in effect.
javax.servlet.ServletContext	getServletContext() Returns a reference to the servlet context in which this application is operating.
SiteIdentifier	getSiteIdentifier() Returns the site identifier in effect for figuring out which site through which a user is making a request.
SiteResourceLoader	getSiteResourceLoader() Returns a reference to the loader used to obtain site-specific resources.
protected String	handleException(javax.servlet.http.HttpServletRequest req, Logic logic, Exception error) If a generic exception propagates up from Logic.invoke(com.samskivert.velocity.Application, com.samskivert.velocity.InvocationContext) and is not otherwise converted into a friendly or redirect exception, the application will be required to provide a generic error message to be inserted into the context and should take this opportunity to log the exception.
void	init(javax.servlet.ServletConfig config, javax.servlet.ServletContext context, String logicPkg) Performs initializations common to all applications.
protected void	prepareContext(InvocationContext ctx) Allows derived aplication classes to prepare an invocation context prior to the logic class being invoked.
void	shutdown() This should be overridden by the application implementation to perform any necessary cleanup.
String	translate(InvocationContext ctx, String msg) A convenience function for translating messages.
String	translate(InvocationContext ctx, String msg, Object... args) A convenience function for translating messages.
protected Exception	translateException(Exception error) If an exception propagates up from Logic.invoke(com.samskivert.velocity.Application, com.samskivert.velocity.InvocationContext), the application is given the chance to convert a low-level exception into a FriendlyException or a RedirectException which will be handled in the normal way.
protected void	willInit(javax.servlet.ServletConfig config) This should be overridden by the application implementation to invoke any necessary pre-initialization code.

Methods inherited from class java.lang.Object

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

Field Detail

VELOCITY_ATTR_KEY

public static final String VELOCITY_ATTR_KEY

An initialized application automatically registers itself as a Velocity application attribute so that it can be retrieved by Velocity plugins using getApplicationAttribute(VELOCITY_ATTR_KEY).

See Also:

Constant Field Values

_context

protected javax.servlet.ServletContext _context

A reference to the servlet context in which this application is operating.

_logicPkg

protected String _logicPkg

The prefix that we use to generate fully qualified logic class names.

_msgmgr

protected MessageManager _msgmgr

A reference to our message manager or null if we have none.

_siteIdent

protected SiteIdentifier _siteIdent

A reference to our site identifier.

_siteLoader

protected SiteResourceLoader _siteLoader

Provides access to site-specific resources.

MESSAGE_BUNDLE_PATH_KEY

protected static final String MESSAGE_BUNDLE_PATH_KEY

The servlet parameter key specifying the path to the application's translated message resources.

See Also:

Constant Field Values

SITE_JAR_PATH_KEY

protected static final String SITE_JAR_PATH_KEY

The servlet parameter key specifying the path to the site-specific jar files.

See Also:

Constant Field Values

SITE_MESSAGE_BUNDLE_PATH_KEY

protected static final String SITE_MESSAGE_BUNDLE_PATH_KEY

The servlet parameter key specifying the path to the site-specific translated message resources.

See Also:

Constant Field Values

Constructor Detail

Application

public Application()

Method Detail

init

public void init(javax.servlet.ServletConfig config,
                 javax.servlet.ServletContext context,
                 String logicPkg)

Performs initializations common to all applications. Applications should override willInit(javax.servlet.ServletConfig) to perform initializations that need to take place before the common initialization (which includes the creation of the site identifier and message manager) and should override didInit(javax.servlet.ServletConfig) to perform initializations that need to take place after the common initialization (like passing the application to entities that might turn around and request a reference to our site identifier).

Parameters:

config - the servlet config from which the application will load configuration information.

context - the servlet context in which this application is operating.

logicPkg - the base package for all of the logic implementations for this application.

configureVelocity

protected void configureVelocity(javax.servlet.ServletConfig config,
                                 Properties props)

Called prior to initializing Velocity to allow the application to specify custom configuration properties.

getInitParameter

protected String getInitParameter(javax.servlet.ServletConfig config,
                                  String key)

Looks up an initialization parameter for this application. The default implementation retrieves the value from the servlet config, but derived classes may wish to get certain parameters from some other configuration source.

createMessageManager

protected MessageManager createMessageManager(String bundlePath)

Creates the message manager to be used for this application.

willInit

protected void willInit(javax.servlet.ServletConfig config)

This should be overridden by the application implementation to invoke any necessary pre-initialization code. They should be sure to call super.willInit().

didInit

protected void didInit(javax.servlet.ServletConfig config)

This should be overridden by the application implementation to invoke any necessary post-initialization code. They should be sure to call super.didInit().

prepareContext

protected void prepareContext(InvocationContext ctx)

Allows derived aplication classes to prepare an invocation context prior to the logic class being invoked. They may wish to add standard tools to the context or do any other request-invariant preparation.

checkAccess

protected void checkAccess(InvocationContext ctx)
                    throws RedirectException,
                           HttpErrorException

Allows derived application classes to check access in a single location prior to resolving and dispatching a logic class, if they desire access control at this level. Alternatively, access control can be performed by the logic instance.

Throws:

RedirectException

HttpErrorException

translateException

protected Exception translateException(Exception error)

If an exception propagates up from Logic.invoke(com.samskivert.velocity.Application, com.samskivert.velocity.InvocationContext), the application is given the chance to convert a low-level exception into a FriendlyException or a RedirectException which will be handled in the normal way.

handleException

protected String handleException(javax.servlet.http.HttpServletRequest req,
                                 Logic logic,
                                 Exception error)

If a generic exception propagates up from Logic.invoke(com.samskivert.velocity.Application, com.samskivert.velocity.InvocationContext) and is not otherwise converted into a friendly or redirect exception, the application will be required to provide a generic error message to be inserted into the context and should take this opportunity to log the exception.

Note: the string returned by this method will be translated using the application's message manager before being inserted into the Velocity context.

shutdown

public void shutdown()

This should be overridden by the application implementation to perform any necessary cleanup.

getServletContext

public javax.servlet.ServletContext getServletContext()

Returns a reference to the servlet context in which this application is operating.

getMessageManager

public MessageManager getMessageManager()

Returns the message manager in effect for this application, if one is in effect.

getSiteIdentifier

public SiteIdentifier getSiteIdentifier()

Returns the site identifier in effect for figuring out which site through which a user is making a request.

getSiteResourceLoader

public SiteResourceLoader getSiteResourceLoader()

Returns a reference to the loader used to obtain site-specific resources. This is only valid if the user specified the site-specific jar file path in the servlet configuration.

See Also:

SITE_JAR_PATH_KEY

createSiteIdentifier

protected SiteIdentifier createSiteIdentifier(javax.servlet.ServletContext ctx)

Called to instantiate the site identifier that we'd like to use in this application. This will be an instance of IndiscriminateSiteIdentifier unless the derived application class overrides this method and creates something more to its liking. This will be called after the application's init(javax.servlet.ServletConfig, javax.servlet.ServletContext, java.lang.String) method has been called.

translate

public final String translate(InvocationContext ctx,
                              String msg)

A convenience function for translating messages.

translate

public final String translate(InvocationContext ctx,
                              String msg,
                              Object... args)

A convenience function for translating messages.

generateClass

protected String generateClass(String path)

Given the servlet path (the part of the URI after the context path) this generates the classname of the logic class that should handle the request.