org.apache.tapestry.engine
Class AbstractEngine

java.lang.Object
  org.apache.tapestry.engine.AbstractEngine

All Implemented Interfaces:

IEngine, WebRequestServicer

Direct Known Subclasses:

BaseEngine

public abstract class AbstractEngine
extends Object
implements IEngine

Basis for building real Tapestry applications. Immediate subclasses provide different strategies for managing page state and other resources between request cycles.

Note: much of this description is in transition as part of Tapestry 4.0. All ad-hoc singletons and such are being replaced with HiveMind services.

Uses a shared instance of TemplateSource,ISpecificationSource, IScriptSourceand ComponentMessagesSourcestored as attributes of the ServletContext(they will be shared by all sessions).

An engine is designed to be very lightweight. Particularily, it should never hold references to any IPageor IComponentobjects. The entire system is based upon being able to quickly rebuild the state of any page(s).

Where possible, instance variables should be transient.

In practice, a subclass (usually BaseEngine) is used without subclassing. Instead, a visit object is specified. To facilitate this, the application specification may include a property, org.apache.tapestry.visit-class which is the class name to instantiate when a visit object is first needed.

Some of the classes' behavior is controlled by JVM system properties (typically only used during development):

Property	Description
org.apache.tapestry.enable-reset-service	If true, enabled an additional service, reset, that allow page, specification and template caches to be cleared on demand.
org.apache.tapestry.disable-caching	If true, then the page, specification, template and script caches will be cleared after each request. This slows things down, but ensures that the latest versions of such files are used. Care should be taken that the source directories for the files preceeds any versions of the files available in JARs or WARs.

Author:

Howard Lewis Ship

Field Summary

static String

VISIT_CLASS_PROPERTY_NAME The name of the application specification property used to specify the class of the visit object.

Constructor Summary

AbstractEngine()

Method Summary

protected void	activateExceptionPage(IRequestCycle cycle, Throwable cause)
protected void	cleanupAfterRequest(IRequestCycle cycle) Invoked at the end of the request cycle to release any resources specific to the request cycle.
org.apache.hivemind.ClassResolver	getClassResolver()
DataSqueezer	getDataSqueezer()
boolean	getHasVisit()
Infrastructure	getInfrastructure() Returns the Infrastructure object, a central registry of key HiveMind services used by Tapestry.
ListenerMap	getListeners() Allows subclasses to include listener methods easily.
Locale	getLocale() Returns the locale for the engine.
String	getOutputEncoding() Returns the encoding to be used to generate the responses and accept the requests.
IPropertySource	getPropertySource()
IScriptSource	getScriptSource()
IEngineService	getService(String name) Returns a service with the given name.
IApplicationSpecification	getSpecification()
ISpecificationSource	getSpecificationSource()
Object	getVisit() Gets the visit object from the ApplicationStateManager, creating it if it does not already exist.
Object	getVisit(IRequestCycle cycle) Gets the visit object from the ApplicationStateManager, which will create it as necessary.
protected void	handlePageRedirectException(IRequestCycle cycle, PageRedirectException exception) Handles PageRedirectException which involves executing IRequestCycle.activate(IPage) on the target page (of the exception), until either a loop is found, or a page succesfully activates.
protected void	handleRedirectException(IRequestCycle cycle, RedirectException redirectException) Invoked when a RedirectException is thrown during the processing of a request.
protected void	handleStaleLinkException(IRequestCycle cycle, StaleLinkException exception) Invoked by service(WebRequest, WebResponse) if a StaleLinkException is thrown by the service.
protected void	handleStaleSessionException(IRequestCycle cycle, StaleSessionException exception) Invoked by service(WebRequest, WebResponse) if a StaleSessionException is thrown by the service.
protected void	redirect(String pageName, IRequestCycle cycle, org.apache.hivemind.ApplicationRuntimeException exception) Invoked, typically, when an exception occurs while servicing the request.
void	renderResponse(IRequestCycle cycle) Delegates to ResponseRenderer.renderResponse(IRequestCycle).
void	reportException(String reportTitle, Throwable ex) Writes a detailed report of the exception to System.err.
void	service(WebRequest request, WebResponse response) Delegate method for the servlet.
void	setLocale(Locale value) Changes the locale for the engine.
void	setVisit(Object visit)
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

VISIT_CLASS_PROPERTY_NAME

public static final String VISIT_CLASS_PROPERTY_NAME

The name of the application specification property used to specify the class of the visit object.

See Also:

Constant Field Values

Constructor Detail

AbstractEngine

public AbstractEngine()

Method Detail

activateExceptionPage

protected void activateExceptionPage(IRequestCycle cycle,
                                     Throwable cause)

See Also:

ExceptionPresenter

reportException

public void reportException(String reportTitle,
                            Throwable ex)

Writes a detailed report of the exception to System.err.

See Also:

RequestExceptionReporter

cleanupAfterRequest

protected void cleanupAfterRequest(IRequestCycle cycle)

Invoked at the end of the request cycle to release any resources specific to the request cycle. This implementation does nothing and may be overriden freely.

getLocale

public Locale getLocale()

Returns the locale for the engine. This is initially set by the ApplicationServlet but may be updated by the application.

Specified by:

getLocale in interface IEngine

getService

public IEngineService getService(String name)

Returns a service with the given name.

See Also:

Infrastructure.getServiceMap(), ServiceMap

getSpecification

public IApplicationSpecification getSpecification()

See Also:

Infrastructure.getApplicationSpecification()

getSpecificationSource

public ISpecificationSource getSpecificationSource()

See Also:

Infrastructure.getSpecificationSource()

redirect

protected void redirect(String pageName,
                        IRequestCycle cycle,
                        org.apache.hivemind.ApplicationRuntimeException exception)
                 throws IOException

Invoked, typically, when an exception occurs while servicing the request. This method resets the output, sets the new page and renders it.

Throws:

IOException

renderResponse

public void renderResponse(IRequestCycle cycle)
                    throws IOException

Delegates to ResponseRenderer.renderResponse(IRequestCycle).

Throws:

IOException

service

public void service(WebRequest request,
                    WebResponse response)
             throws IOException

Delegate method for the servlet. Services the request.

Specified by:

service in interface WebRequestServicer

Throws:

IOException

handlePageRedirectException

protected void handlePageRedirectException(IRequestCycle cycle,
                                           PageRedirectException exception)
                                    throws IOException

Handles PageRedirectException which involves executing IRequestCycle.activate(IPage) on the target page (of the exception), until either a loop is found, or a page succesfully activates.

This should generally not be overriden in subclasses.

Throws:

IOException

Since:

3.0

handleStaleLinkException

protected void handleStaleLinkException(IRequestCycle cycle,
                                        StaleLinkException exception)
                                 throws IOException

Invoked by service(WebRequest, WebResponse) if a StaleLinkException is thrown by the service. This implementation sets the message property of the StaleLink page to the message provided in the exception, then invokes redirect(String, IRequestCycle, ApplicationRuntimeException) to render the StaleLink page.

Subclasses may overide this method (without invoking this implementation). A better practice is to contribute an alternative implementation of StaleLinkExceptionPresenter to the tapestry.InfrastructureOverrides configuration point.

A common practice is to present an error message on the application's Home page. Alternately, the application may provide its own version of the StaleLink page, overriding the framework's implementation (probably a good idea, because the default page hints at "application errors" and isn't localized). The overriding StaleLink implementation must implement a message property of type String.

Throws:

IOException

Since:

0.2.10

handleStaleSessionException

protected void handleStaleSessionException(IRequestCycle cycle,
                                           StaleSessionException exception)
                                    throws IOException

Invoked by service(WebRequest, WebResponse) if a StaleSessionException is thrown by the service. This implementation uses the StaleSessionExceptionPresenter to render the StaleSession page.

Subclasses may overide this method (without invoking this implementation), but it is better to override the tapestry.error.StaleSessionExceptionReporter service instead (or contribute a replacement to the tapestry.InfrastructureOverrides configuration point).

Throws:

IOException

Since:

0.2.10

setLocale

public void setLocale(Locale value)

Changes the locale for the engine.

Specified by:

setLocale in interface IEngine

getClassResolver

public org.apache.hivemind.ClassResolver getClassResolver()

See Also:

Infrastructure.getClassResolver()

toString

public String toString()

Overrides:

toString in class Object

getVisit

public Object getVisit()

Gets the visit object from the ApplicationStateManager, creating it if it does not already exist.

As of Tapestry 4.0, this will always create the visit object, possibly creating a new session in the process.

setVisit

public void setVisit(Object visit)

getVisit

public Object getVisit(IRequestCycle cycle)

Gets the visit object from the ApplicationStateManager, which will create it as necessary.

getHasVisit

public boolean getHasVisit()

getScriptSource

public IScriptSource getScriptSource()

getListeners

public ListenerMap getListeners()

Allows subclasses to include listener methods easily.

Since:

1.0.2

handleRedirectException

protected void handleRedirectException(IRequestCycle cycle,
                                       RedirectException redirectException)

Invoked when a RedirectException is thrown during the processing of a request.

Throws:

org.apache.hivemind.ApplicationRuntimeException - if an IOException,ServletExceptionis thrown by the redirect, or if no RequestDispatcher can be found for local resource.

Since:

2.2

getDataSqueezer

public DataSqueezer getDataSqueezer()

See Also:

Infrastructure.getDataSqueezer()

getPropertySource

public IPropertySource getPropertySource()

Since:

2.3

getInfrastructure

public Infrastructure getInfrastructure()

Description copied from interface: IEngine

Returns the Infrastructure object, a central registry of key HiveMind services used by Tapestry.

Specified by:

getInfrastructure in interface IEngine

Since:

4.0

getOutputEncoding

public String getOutputEncoding()

Description copied from interface: IEngine

Returns the encoding to be used to generate the responses and accept the requests.

Specified by:

getOutputEncoding in interface IEngine