org.apache.tapestry.engine
Class AbstractEngine

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

All Implemented Interfaces:

Externalizable, Serializable, EventListener, HttpSessionBindingListener, IEngineServiceView, IEngine

Direct Known Subclasses:

BaseEngine

public abstract class AbstractEngine
extends Object
implements IEngine, IEngineServiceView, Externalizable, HttpSessionBindingListener

Basis for building real Tapestry applications. Immediate subclasses provide different strategies for managing page state and other resources between request cycles. Uses a shared instance of ITemplateSource, ISpecificationSource, IScriptSource and IComponentMessagesSource stored as attributes of the ServletContext (they will be shared by all sessions).

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

Where possible, instance variables should be transient. They can be restored inside setupForRequest(RequestContext).

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. See createVisit(IRequestCycle) for more details.

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. See isResetServiceEnabled().
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.

Version:

$Id: AbstractEngine.java 244181 2005-03-19 00:46:51Z pferraro $

Author:

Howard Lewis Ship

See Also:

Serialized Form

Field Summary

protected IApplicationSpecification	_specification The specification for the application, which lives in the ServletContext.
protected ISpecificationSource	_specificationSource The source for component specifications, stored in the ServletContext (like _templateSource).
protected ITemplateSource	_templateSource The source for template data.
protected static String	DATA_SQUEEZER_NAME Servlet context attribute name for a shared instance of DataSqueezer.
static String	DEFAULT_OUTPUT_ENCODING The default encoding that will be used when generating the output.
protected static String	ENHANCER_NAME Name of a shared instance of IComponentClassEnhancer stored in the ServletContext.
static String	GLOBAL_NAME The base name for the servlet context key used to store the application-defined Global object, if any.
static String	OUTPUT_ENCODING_PROPERTY_NAME The name of the application property that will be used to determine the encoding to use when generating the output
protected static String	PAGE_SOURCE_NAME Servlet context attribute name for the IPageSource instance.
protected static String	POOL_NAME
protected static String	PROPERTY_SOURCE_NAME Constant used to store a IPropertyHolder in the servlet context.
protected static String	RESOURCE_CHECKSUM_SOURCE_NAME Servlet context attribute name for a shared instance of ResourceChecksumSource.
protected static String	SCRIPT_SOURCE_NAME The name of the context attribute for the IScriptSource instance.
protected static String	SERVICE_MAP_NAME
protected static String	SPECIFICATION_SOURCE_NAME Servlet context attribute name for the default ISpecificationSource instance.
protected static String	STRINGS_SOURCE_NAME The name of the context attribute for the IComponentMessagesSource instance.
protected static String	TEMPLATE_SOURCE_NAME Servlet context attribute name for the default ITemplateSource instance.
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, ResponseOutputStream output, Throwable cause) Sets the Exception page's exception property, then renders the Exception page.
protected abstract void	cleanupAfterRequest(IRequestCycle cycle) Invoked at the end of the request cycle to release any resources specific to the request cycle.
void	clearCachedData() Discards all cached pages, component specifications and templates.
protected IComponentClassEnhancer	createComponentClassEnhancer(RequestContext context) Invoked from setupForRequest(RequestContext).
IComponentMessagesSource	createComponentStringsSource(RequestContext context) Invoked from setupForRequest(RequestContext) to provide a new instance of IComponentMessagesSource.
DataSqueezer	createDataSqueezer() Invoked from setupForRequest(RequestContext) to create a DataSqueezer when needed (typically, just the very first time).
protected Object	createGlobal(RequestContext context) Creates the shared Global object.
protected IPageSource	createPageSource(RequestContext context) Invoked from setupForRequest(RequestContext) to provide an instance of IPageSource that will be stored into the ServletContext.
protected Pool	createPool(RequestContext context) Returns an new instance of Pool, with the standard set of adaptors, plus BSFManagerPoolableAdaptor for BSFManager.
protected IPropertySource	createPropertySource(RequestContext context) Creates a shared property source that will be stored into the servlet context.
protected IRequestCycle	createRequestCycle(RequestContext context, IEngineService service, IMonitor monitor) Invoked from service(RequestContext) to create an instance of IRequestCycle for the current request.
protected ResourceChecksumSource	createResourceChecksumSource() Invoked from setupForRequest(RequestContext) to provide an instance of ResourceChecksumSource that will be stored into the ServletContext.
protected IScriptSource	createScriptSource(RequestContext context) Invoked from setupForRequest(RequestContext) to provide an instance of IScriptSource that will be stored into the ServletContext.
protected ISpecificationSource	createSpecificationSource(RequestContext context) Invoked from setupForRequest(RequestContext) to provide an instance of ISpecificationSource that will be stored into the ServletContext.
protected ITemplateSource	createTemplateSource(RequestContext context) Invoked from setupForRequest(RequestContext) to provide an instance of ITemplateSource that will be stored into the ServletContext.
protected Object	createVisit(IRequestCycle cycle) Invoked to lazily create a new visit object when it is first referenced (by getVisit(IRequestCycle)).
protected void	extendDescription(org.apache.commons.lang.builder.ToStringBuilder builder) Extends the description of the class generated by toString().
protected String	extractServiceName(RequestContext context) Invoked from service(RequestContext) to extract, from the URL, the name of the service.
abstract Collection	getActivePageNames() Implemented by subclasses to return the names of the active pages (pages for which recorders exist).
IComponentClassEnhancer	getComponentClassEnhancer() Returns an object that can create enhanced versions of component classes.
IComponentMessagesSource	getComponentMessagesSource() Returns a shared object that allows components to find their set of localized strings.
String	getContextPath() Returns the context path, the prefix to apply to any URLs so that they are recognized as belonging to the Servlet 2.2 context.
DataSqueezer	getDataSqueezer() Returns a shared instance of DataSqueezer.
protected String	getDefaultOutputEncoding() The encoding to be used if none has been defined using the output encoding property.
protected String	getExceptionPageName()
Object	getGlobal() Returns the global object for the application.
boolean	getHasVisit()
ListenerMap	getListeners() Allows subclasses to include listener methods easily.
Locale	getLocale() Returns the locale for the engine.
IMonitor	getMonitor(RequestContext context) Overriden in subclasses that support monitoring.
String	getOutputEncoding() Returns the encoding to be used to generate the servlet responses and accept the servlet requests.
IPageSource	getPageSource() Returns the object used to load a page from its specification.
Pool	getPool() Returns a Pool that is used to store all manner of objects that are needed throughout the system.
IPropertySource	getPropertySource() Returns a IPropertySource that should be used to obtain configuration data.
ResourceChecksumSource	getResourceChecksumSource() Returns an object that can compute the checksum of a resource.
IResourceResolver	getResourceResolver() Returns an object which can find resources and classes.
IScriptSource	getScriptSource() Returns a source for parsed IScripts.
IEngineService	getService(String name) Returns a service with the given name.
String	getServletPath() Returns the URL path that corresponds to the servlet for the application.
IApplicationSpecification	getSpecification() Returns the specification, if available, or null otherwise.
ISpecificationSource	getSpecificationSource() Returns the source of all component specifications for the application.
protected String	getStaleLinkPageName()
protected String	getStaleSessionPageName()
ITemplateSource	getTemplateSource() Returns the source for HTML templates.
Object	getVisit() Gets the visit object, if it has been created already.
Object	getVisit(IRequestCycle cycle) Gets the visit object, invoking createVisit(IRequestCycle) to create it lazily if needed.
protected void	handlePageRedirectException(PageRedirectException ex, IRequestCycle cycle, ResponseOutputStream output) Handles PageRedirectException which involves executing IPage.validate(IRequestCycle) on the target page (of the exception), until either a loop is found, or a page succesfully validates and can be activated.
protected void	handleRedirectException(IRequestCycle cycle, RedirectException ex) Invoked when a RedirectException is thrown during the processing of a request.
protected void	handleStaleLinkException(StaleLinkException ex, IRequestCycle cycle, ResponseOutputStream output) Invoked by service(RequestContext) if a StaleLinkException is thrown by the service.
protected void	handleStaleSessionException(StaleSessionException ex, IRequestCycle cycle, ResponseOutputStream output) Invoked by service(RequestContext) if a StaleSessionException is thrown by the service.
boolean	isDirty() Returns true if the engine has (potentially) changed state since the last time it was stored into the HttpSession.
boolean	isResetServiceEnabled() Returns true if the reset service is curently enabled.
boolean	isStateful() Returns true if the engine has state and, therefore, should be stored in the HttpSession.
protected void	markDirty() Invoked to set the dirty flag, indicating that the engine should be stored into the HttpSession.
void	readExternal(ObjectInput in) Reads the state serialized by writeExternal(ObjectOutput).
protected void	redirect(String pageName, IRequestCycle cycle, ResponseOutputStream out, ApplicationRuntimeException exception) Invoked, typically, when an exception occurs while servicing the request.
void	renderResponse(IRequestCycle cycle, ResponseOutputStream output) Invoked by a service to force the page selected by the IRequestCycle to be renderred.
void	reportException(String reportTitle, Throwable ex) Writes a detailed report of the exception to System.err.
void	restart(IRequestCycle cycle) Invalidates the session, then redirects the client web browser to the servlet's prefix, starting a new visit.
boolean	service(RequestContext context) Delegate method for the servlet.
void	setLocale(Locale value) Changes the locale for the engine.
protected void	setStateful() Invoked by subclasses to indicate that some state must now be stored in the engine (and that the engine should now be stored in the HttpSession).
protected void	setupForRequest(RequestContext context) Invoked from service(RequestContext) to ensure that the engine's instance variables are setup.
void	setVisit(Object value) Updates the visit object and sets the dirty flag.
String	toString() Generates a description of the instance.
void	valueBound(HttpSessionBindingEvent arg0) Clears the dirty flag when a engine is stored into the HttpSession.
void	valueUnbound(HttpSessionBindingEvent arg0) Does nothing.
void	writeExternal(ObjectOutput out) Writes the following properties: locale name (Locale.toString()) visit

Methods inherited from class java.lang.Object

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

Field Detail

GLOBAL_NAME

public static final String GLOBAL_NAME

The base name for the servlet context key used to store the application-defined Global object, if any.

Since:

2.3

See Also:

Constant Field Values

OUTPUT_ENCODING_PROPERTY_NAME

public static final String OUTPUT_ENCODING_PROPERTY_NAME

The name of the application property that will be used to determine the encoding to use when generating the output

Since:

3.0

See Also:

Constant Field Values

DEFAULT_OUTPUT_ENCODING

public static final String DEFAULT_OUTPUT_ENCODING

The default encoding that will be used when generating the output. It is used if no output encoding property has been specified.

Since:

3.0

See Also:

Constant Field Values

_specification

protected transient IApplicationSpecification _specification

The specification for the application, which lives in the ServletContext. If the session (and application) moves to a different context (i.e., a different JVM), then we want to reconnect to the specification in the new context. A check is made on every request cycle as needed.

_templateSource

protected transient ITemplateSource _templateSource

The source for template data. The template source is stored in the ServletContext as a named attribute. After de-serialization, the application can re-connect to the template source (or create a new one).

_specificationSource

protected transient ISpecificationSource _specificationSource

The source for component specifications, stored in the ServletContext (like _templateSource).

SCRIPT_SOURCE_NAME

protected static final String SCRIPT_SOURCE_NAME

The name of the context attribute for the IScriptSource instance. The application's name is appended.

Since:

1.0.2

See Also:

Constant Field Values

STRINGS_SOURCE_NAME

protected static final String STRINGS_SOURCE_NAME

The name of the context attribute for the IComponentMessagesSource instance. The application's name is appended.

Since:

2.0.4

See Also:

Constant Field Values

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

TEMPLATE_SOURCE_NAME

protected static final String TEMPLATE_SOURCE_NAME

Servlet context attribute name for the default ITemplateSource instance. The application's name is appended.

See Also:

Constant Field Values

SPECIFICATION_SOURCE_NAME

protected static final String SPECIFICATION_SOURCE_NAME

Servlet context attribute name for the default ISpecificationSource instance. The application's name is appended.

See Also:

Constant Field Values

PAGE_SOURCE_NAME

protected static final String PAGE_SOURCE_NAME

Servlet context attribute name for the IPageSource instance. The application's name is appended.

See Also:

Constant Field Values

DATA_SQUEEZER_NAME

protected static final String DATA_SQUEEZER_NAME

Servlet context attribute name for a shared instance of DataSqueezer. The instance is actually shared between Tapestry applications within the same context (which will have the same ClassLoader).

Since:

2.2

See Also:

Constant Field Values

RESOURCE_CHECKSUM_SOURCE_NAME

protected static final String RESOURCE_CHECKSUM_SOURCE_NAME

Servlet context attribute name for a shared instance of ResourceChecksumSource.

Since:

3.0.3

See Also:

Constant Field Values

PROPERTY_SOURCE_NAME

protected static final String PROPERTY_SOURCE_NAME

Constant used to store a IPropertyHolder in the servlet context.

Since:

2.3

See Also:

Constant Field Values

SERVICE_MAP_NAME

protected static final String SERVICE_MAP_NAME

See Also:

Constant Field Values

POOL_NAME

protected static final String POOL_NAME

See Also:

Constant Field Values

ENHANCER_NAME

protected static final String ENHANCER_NAME

Name of a shared instance of IComponentClassEnhancer stored in the ServletContext.

Since:

3.0

See Also:

Constant Field Values

Constructor Detail

AbstractEngine

public AbstractEngine()

Method Detail

activateExceptionPage

protected void activateExceptionPage(IRequestCycle cycle,
                                     ResponseOutputStream output,
                                     Throwable cause)
                              throws ServletException

Sets the Exception page's exception property, then renders the Exception page.

If the render throws an exception, then copious output is sent to System.err and a ServletException is thrown.

Throws:

ServletException

reportException

public void reportException(String reportTitle,
                            Throwable ex)

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

Specified by:

reportException in interface IEngineServiceView

cleanupAfterRequest

protected abstract void cleanupAfterRequest(IRequestCycle cycle)

Invoked at the end of the request cycle to release any resources specific to the request cycle.

extendDescription

protected void extendDescription(org.apache.commons.lang.builder.ToStringBuilder builder)

Extends the description of the class generated by toString(). If a subclass adds additional instance variables that should be described in the instance description, it may overide this method. This implementation does nothing.

See Also:

toString()

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

getMonitor

public IMonitor getMonitor(RequestContext context)

Overriden in subclasses that support monitoring. Should create and return an instance of IMonitor that is appropriate for the request cycle described by the RequestContext.

The monitor is used to create a RequestCycle.

This implementation uses a IMonitorFactory to create the monitor instance. The factory is provided as an application extension. If the application extension does not exist, DefaultMonitorFactory is used.

As of release 3.0, this method should not return null.

getPageSource

public IPageSource getPageSource()

Description copied from interface: IEngine

Returns the object used to load a page from its specification.

Specified by:

getPageSource in interface IEngine

getService

public IEngineService getService(String name)

Returns a service with the given name. Services are created by the first call to setupForRequest(RequestContext).

Specified by:

getService in interface IEngine

getServletPath

public String getServletPath()

Description copied from interface: IEngine

Returns the URL path that corresponds to the servlet for the application. This is required by instances of IEngineService that need to construct URLs for the application. This value will include the context path.

Specified by:

getServletPath in interface IEngine

getContextPath

public String getContextPath()

Returns the context path, the prefix to apply to any URLs so that they are recognized as belonging to the Servlet 2.2 context.

Specified by:

getContextPath in interface IEngine

See Also:

ContextAsset

getSpecification

public IApplicationSpecification getSpecification()

Returns the specification, if available, or null otherwise.

To facilitate deployment across multiple servlet containers, the application is serializable. However, the reference to the specification is transient. When an application instance is deserialized, it reconnects with the application specification by locating it in the ServletContext or parsing it fresh.

Specified by:

getSpecification in interface IEngine

getSpecificationSource

public ISpecificationSource getSpecificationSource()

Description copied from interface: IEngine

Returns the source of all component specifications for the application. The source is shared between sessions.

Specified by:

getSpecificationSource in interface IEngine

See Also:

createSpecificationSource(RequestContext)

getTemplateSource

public ITemplateSource getTemplateSource()

Description copied from interface: IEngine

Returns the source for HTML templates.

Specified by:

getTemplateSource in interface IEngine

See Also:

createTemplateSource(RequestContext)

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Reads the state serialized by writeExternal(ObjectOutput).

This always set the stateful flag. By default, a deserialized session is stateful (else, it would not have been serialized).

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Writes the following properties:

• locale name (Locale.toString())
• visit

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

redirect

protected void redirect(String pageName,
                        IRequestCycle cycle,
                        ResponseOutputStream out,
                        ApplicationRuntimeException exception)
                 throws IOException,
                        ServletException

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

Throws:

IOException

ServletException

renderResponse

public void renderResponse(IRequestCycle cycle,
                           ResponseOutputStream output)
                    throws ServletException,
                           IOException

Description copied from interface: IEngineServiceView

Invoked by a service to force the page selected by the IRequestCycle to be renderred. This takes care of a number of bookkeeping issues, such as committing changes in page recorders.

Specified by:

renderResponse in interface IEngineServiceView

Throws:

ServletException

IOException

restart

public void restart(IRequestCycle cycle)
             throws IOException

Invalidates the session, then redirects the client web browser to the servlet's prefix, starting a new visit.

Subclasses should perform their own restart (if necessary, which is rarely) before invoking this implementation.

Specified by:

restart in interface IEngineServiceView

Throws:

IOException

service

public boolean service(RequestContext context)
                throws ServletException,
                       IOException

Delegate method for the servlet. Services the request.

Specified by:

service in interface IEngine

Returns:

true if the state of the engine was, or could have been, changed during processing.

Throws:

ServletException

IOException

handlePageRedirectException

protected void handlePageRedirectException(PageRedirectException ex,
                                           IRequestCycle cycle,
                                           ResponseOutputStream output)
                                    throws IOException,
                                           ServletException

Handles PageRedirectException which involves executing IPage.validate(IRequestCycle) on the target page (of the exception), until either a loop is found, or a page succesfully validates and can be activated.

This should generally not be overriden in subclasses.

Throws:

IOException

ServletException

Since:

3.0

createRequestCycle

protected IRequestCycle createRequestCycle(RequestContext context,
                                           IEngineService service,
                                           IMonitor monitor)

Invoked from service(RequestContext) to create an instance of IRequestCycle for the current request. This implementation creates an returns an instance of RequestCycle.

Since:

3.0

handleStaleLinkException

protected void handleStaleLinkException(StaleLinkException ex,
                                        IRequestCycle cycle,
                                        ResponseOutputStream output)
                                 throws IOException,
                                        ServletException

Invoked by service(RequestContext) 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, ResponseOutputStream, ApplicationRuntimeException) to render the StaleLink page.

Subclasses may overide this method (without invoking this implementation). 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

ServletException

Since:

0.2.10

handleStaleSessionException

protected void handleStaleSessionException(StaleSessionException ex,
                                           IRequestCycle cycle,
                                           ResponseOutputStream output)
                                    throws IOException,
                                           ServletException

Invoked by service(RequestContext) if a StaleSessionException is thrown by the service. This implementation invokes redirect(String, IRequestCycle, ResponseOutputStream, ApplicationRuntimeException) to render the StaleSession page.

Subclasses may overide this method (without invoking this implementation). A common practice is to present an eror message on the application's Home page.

Throws:

IOException

ServletException

Since:

0.2.10

clearCachedData

public void clearCachedData()

Discards all cached pages, component specifications and templates. Subclasses who override this method should invoke this implementation as well.

Specified by:

clearCachedData in interface IEngineServiceView

Since:

1.0.1

setLocale

public void setLocale(Locale value)

Changes the locale for the engine.

Specified by:

setLocale in interface IEngine

setupForRequest

protected void setupForRequest(RequestContext context)

Invoked from service(RequestContext) to ensure that the engine's instance variables are setup. This allows the application a chance to restore transient variables that will not have survived deserialization. Determines the servlet prefix: this is the base URL used by services to build URLs. It consists of two parts: the context path and the servlet path.

The servlet path is retrieved from HttpServletRequest.getServletPath().

The context path is retrieved from HttpServletRequest.getContextPath().

The global object is retrieved from IEngine.getGlobal() method.

The final path is available via the getServletPath() method.

In addition, this method locates and/or creates the:

• IComponentClassEnhancer
• Pool
• ITemplateSource
• ISpecificationSource
• IPageSource
• IEngineService Map IScriptSource
• IComponentMessagesSource
• IPropertySource

This order is important, because some of the later shared objects depend on some of the earlier shared objects already having been located or created (especially pool).

Subclasses should invoke this implementation first, then perform their own setup.

createComponentStringsSource

public IComponentMessagesSource createComponentStringsSource(RequestContext context)

Invoked from setupForRequest(RequestContext) to provide a new instance of IComponentMessagesSource.

Returns:

an instance of DefaultComponentMessagesSource

Since:

2.0.4

createScriptSource

protected IScriptSource createScriptSource(RequestContext context)

Invoked from setupForRequest(RequestContext) to provide an instance of IScriptSource that will be stored into the ServletContext. Subclasses may override this method to provide a different implementation.

Returns:

an instance of DefaultScriptSource

Since:

1.0.9

createPageSource

protected IPageSource createPageSource(RequestContext context)

Invoked from setupForRequest(RequestContext) to provide an instance of IPageSource that will be stored into the ServletContext. Subclasses may override this method to provide a different implementation.

Returns:

an instance of PageSource

Since:

1.0.9

createSpecificationSource

protected ISpecificationSource createSpecificationSource(RequestContext context)

Invoked from setupForRequest(RequestContext) to provide an instance of ISpecificationSource that will be stored into the ServletContext. Subclasses may override this method to provide a different implementation.

Returns:

an instance of DefaultSpecificationSource

Since:

1.0.9

createTemplateSource

protected ITemplateSource createTemplateSource(RequestContext context)

Invoked from setupForRequest(RequestContext) to provide an instance of ITemplateSource that will be stored into the ServletContext. Subclasses may override this method to provide a different implementation.

Returns:

an instance of DefaultTemplateSource

Since:

1.0.9

createResourceChecksumSource

protected ResourceChecksumSource createResourceChecksumSource()

Invoked from setupForRequest(RequestContext) to provide an instance of ResourceChecksumSource that will be stored into the ServletContext. Subclasses may override this method to provide a different implementation.

Returns:

an instance of ResourceChecksumSourceImpl that uses MD5 and Hex encoding.

Since:

3.0.3

getResourceResolver

public IResourceResolver getResourceResolver()

Returns an object which can find resources and classes.

Specified by:

getResourceResolver in interface IEngine

toString

public String toString()

Generates a description of the instance. Invokes extendDescription(ToStringBuilder) to fill in details about the instance.

Overrides:

toString in class Object

See Also:

extendDescription(ToStringBuilder)

isResetServiceEnabled

public boolean isResetServiceEnabled()

Returns true if the reset service is curently enabled.

Specified by:

isResetServiceEnabled in interface IEngine

getActivePageNames

public abstract Collection getActivePageNames()

Implemented by subclasses to return the names of the active pages (pages for which recorders exist). May return the empty list, but should not return null.

getVisit

public Object getVisit()

Gets the visit object, if it has been created already.

If the visit is non-null then the isDirty() flag is set (because the engine can't tell what the caller will do with the visit).

Specified by:

getVisit in interface IEngine

getVisit

public Object getVisit(IRequestCycle cycle)

Gets the visit object, invoking createVisit(IRequestCycle) to create it lazily if needed. If cycle is null, the visit will not be lazily created.

After creating the visit, but before returning, the HttpSession will be created, and setStateful() will be invoked.

Sets the isDirty() flag, if the return value is not null.

Specified by:

getVisit in interface IEngine

setVisit

public void setVisit(Object value)

Updates the visit object and sets the dirty flag.

Specified by:

setVisit in interface IEngine

getHasVisit

public boolean getHasVisit()

createVisit

protected Object createVisit(IRequestCycle cycle)

Invoked to lazily create a new visit object when it is first referenced (by getVisit(IRequestCycle)). This implementation works by looking up the name of the class to instantiate in the configuration.

Subclasses may want to overide this method if some other means of instantiating a visit object is required.

getGlobal

public Object getGlobal()

Returns the global object for the application. The global object is created at the start of the request (setupForRequest(RequestContext) invokes createGlobal(RequestContext) if needed), and is stored into the ServletContext. All instances of the engine for the application share the global object; however, the global object is explicitly not replicated to other servers within a cluster.

Specified by:

getGlobal in interface IEngine

Since:

2.3

getScriptSource

public IScriptSource getScriptSource()

Description copied from interface: IEngine

Returns a source for parsed IScripts. The source is shared between all sessions.

Specified by:

getScriptSource in interface IEngine

isStateful

public boolean isStateful()

Description copied from interface: IEngine

Returns true if the engine has state and, therefore, should be stored in the HttpSession. This starts as false, but becomes true when the engine requires state (such as when a visit object is created, or when a peristent page property is set).

Specified by:

isStateful in interface IEngine

setStateful

protected void setStateful()

Invoked by subclasses to indicate that some state must now be stored in the engine (and that the engine should now be stored in the HttpSession). The caller is responsible for actually creating the HttpSession (it will have access to the RequestContext).

Since:

1.0.2

getListeners

public ListenerMap getListeners()

Allows subclasses to include listener methods easily.

Since:

1.0.2

handleRedirectException

protected void handleRedirectException(IRequestCycle cycle,
                                       RedirectException ex)

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

Throws:

ApplicationRuntimeException - if an IOException, ServletException is thrown by the redirect, or if no RequestDispatcher can be found for local resource.

Since:

2.2

getComponentMessagesSource

public IComponentMessagesSource getComponentMessagesSource()

Description copied from interface: IEngine

Returns a shared object that allows components to find their set of localized strings.

Specified by:

getComponentMessagesSource in interface IEngine

Since:

2.0.4

See Also:

createComponentStringsSource(RequestContext)

getDataSqueezer

public DataSqueezer getDataSqueezer()

Description copied from interface: IEngine

Returns a shared instance of DataSqueezer.

Specified by:

getDataSqueezer in interface IEngine

Since:

2.2

See Also:

createDataSqueezer()

createDataSqueezer

public DataSqueezer createDataSqueezer()

Invoked from setupForRequest(RequestContext) to create a DataSqueezer when needed (typically, just the very first time). This implementation returns a standard, new instance.

Since:

2.2

extractServiceName

protected String extractServiceName(RequestContext context)

Invoked from service(RequestContext) to extract, from the URL, the name of the service. The current implementation expects the first pathInfo element to be the service name. At some point in the future, the method of constructing and parsing URLs may be abstracted into a developer-selected class.

Subclasses may override this method if the application defines specific services with unusual URL encoding rules.

This implementation simply extracts the value for query parameter Tapestry.SERVICE_QUERY_PARAMETER_NAME and extracts the service name from that.

For supporting the JSP tags, this method first checks for attribute Tapestry.TAG_SUPPORT_SERVICE_ATTRIBUTE. If non-null, then Tapestry.TAGSUPPORT_SERVICE is returned.

Since:

2.2

getPropertySource

public IPropertySource getPropertySource()

Description copied from interface: IEngine

Returns a IPropertySource that should be used to obtain configuration data. The returned source represents a search path that includes (at a minimum):

• Properties of the ApplicationSpecification
• Initial Parameters of servlet (configured in the web.xml deployment descriptor)
• Initial Parameter of the servlet context (also configured in web.xml)
• System properties (defined with the -D JVM command line parameter)
• Hard-coded "factory defaults" (for some properties)

Specified by:

getPropertySource in interface IEngine

Since:

2.3

See Also:

createPropertySource(RequestContext)

getResourceChecksumSource

public ResourceChecksumSource getResourceChecksumSource()

Description copied from interface: IEngine

Returns an object that can compute the checksum of a resource.

Specified by:

getResourceChecksumSource in interface IEngine

Since:

3.0.3

getExceptionPageName

protected String getExceptionPageName()

Since:

3.0

getStaleLinkPageName

protected String getStaleLinkPageName()

Since:

3.0

getStaleSessionPageName

protected String getStaleSessionPageName()

Since:

3.0

createPropertySource

protected IPropertySource createPropertySource(RequestContext context)

Creates a shared property source that will be stored into the servlet context. Subclasses may override this method to build thier own search path.

If the application specification contains an extension named "org.apache.tapestry.property-source" it is inserted in the search path just before the property source for JVM System Properties. This is a simple hook at allow application-specific methods of obtaining configuration values (typically, from a database or from JMX, in some way). Alternately, subclasses may override this method to provide whatever search path is appropriate.

Since:

2.3

createGlobal

protected Object createGlobal(RequestContext context)

Creates the shared Global object. This implementation looks for an configuration property, org.apache.tapestry.global-class, and instantiates that class using a no-arguments constructor. If the property is not defined, a synchronized HashMap is created.

Since:

2.3

createPool

protected Pool createPool(RequestContext context)

Returns an new instance of Pool, with the standard set of adaptors, plus BSFManagerPoolableAdaptor for BSFManager.

Subclasses may override this method to configure the Pool differently.

Since:

3.0

getPool

public Pool getPool()

Description copied from interface: IEngine

Returns a Pool that is used to store all manner of objects that are needed throughout the system. This is the best way to deal with objects that are both expensive to create and not threadsafe. The reset service will clear out this Pool.

Specified by:

getPool in interface IEngine

Since:

3.0

See Also:

createPool(RequestContext)

createComponentClassEnhancer

protected IComponentClassEnhancer createComponentClassEnhancer(RequestContext context)

Invoked from setupForRequest(RequestContext). Creates a new instance of DefaultComponentClassEnhancer. Subclasses may override to return a different object.

Check the property org.apache.tapestry.enhance.disable-abstract-method-validation and, if true, disables abstract method validation. This is used in some errant JDK's (such as IBM's 1.3.1) that incorrectly report concrete methods from abstract classes as abstract.

Since:

3.0

getComponentClassEnhancer

public IComponentClassEnhancer getComponentClassEnhancer()

Description copied from interface: IEngine

Returns an object that can create enhanced versions of component classes.

Specified by:

getComponentClassEnhancer in interface IEngine

Since:

3.0

See Also:

createComponentClassEnhancer(RequestContext)

isDirty

public boolean isDirty()

Returns true if the engine has (potentially) changed state since the last time it was stored into the HttpSession. Various events set this property to true.

Since:

3.0

markDirty

protected void markDirty()

Invoked to set the dirty flag, indicating that the engine should be stored into the HttpSession.

Since:

3.0

valueBound

public void valueBound(HttpSessionBindingEvent arg0)

Clears the dirty flag when a engine is stored into the HttpSession.

Specified by:

valueBound in interface HttpSessionBindingListener

Since:

3.0

valueUnbound

public void valueUnbound(HttpSessionBindingEvent arg0)

Does nothing.

Specified by:

valueUnbound in interface HttpSessionBindingListener

Since:

3.0

getDefaultOutputEncoding

protected String getDefaultOutputEncoding()

The encoding to be used if none has been defined using the output encoding property. Override this method to change the default.

Returns:

the default output encoding

Since:

3.0

getOutputEncoding

public String getOutputEncoding()

Returns the encoding to be used to generate the servlet responses and accept the servlet requests. The encoding is defined using the org.apache.tapestry.output-encoding and is UTF-8 by default

Specified by:

getOutputEncoding in interface IEngine

Since:

3.0

See Also:

IEngine.getOutputEncoding()