org.apache.tapestry
Interface IEngine

All Known Subinterfaces:

IEngineServiceView

All Known Implementing Classes:

AbstractEngine, BaseEngine, WMLEngine

public interface IEngine

Defines the core, session-persistant object used to run a Tapestry application for a single client (each client will have its own instance of the engine).

The engine exists to provide core services to the pages and components that make up the application. The engine is a delegate to the ApplicationServlet via the service(RequestContext) method.

Engine instances are persisted in the HttpSession and are serializable.

Version:

$Id: IEngine.java 244167 2005-03-17 08:14:54Z pferraro $

Author:

Howard Lewis Ship

Field Summary

static String	EXCEPTION_PAGE The name ("Exception") of the page used for reporting exceptions.
static String	HOME_PAGE The name ("Home") of the default page presented when a user first accesses the application.
static String	STALE_LINK_PAGE The name ("StaleLink") of the page used for reporting stale links.
static String	STALE_SESSION_PAGE The name ("StaleSession") of the page used for reporting state sessions.

Method Summary

IPageRecorder	createPageRecorder(String pageName, IRequestCycle cycle) Creates a new page recorder for the named page.
void	forgetPage(String name) Forgets changes to the named page by discarding the page recorder for the page.
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, a string which is prepended to the names of any assets or servlets.
DataSqueezer	getDataSqueezer() Returns a shared instance of DataSqueezer.
Object	getGlobal() Returns the globally shared application object.
Locale	getLocale() Returns the locale for the engine.
String	getOutputEncoding() Returns the encoding to be used to generate the servlet responses and accept the servlet requests.
IPageRecorder	getPageRecorder(String pageName, IRequestCycle cycle) Returns a recorder for a page.
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 that can resolve resources and classes.
IScriptSource	getScriptSource() Returns a source for parsed IScripts.
IEngineService	getService(String name) Gets the named service, or throws an ApplicationRuntimeException if the application can't provide the named server.
String	getServletPath() Returns the URL path that corresponds to the servlet for the application.
IApplicationSpecification	getSpecification() Returns the application specification that defines the application and its pages.
ISpecificationSource	getSpecificationSource() Returns the source of all component specifications for the application.
ITemplateSource	getTemplateSource() Returns the source for HTML templates.
Object	getVisit() Returns the visit object, an object that represents the client's visit to the application.
Object	getVisit(IRequestCycle cycle) Returns the visit object, creating it if necessary.
boolean	isResetServiceEnabled() Returns true if the application allows the reset service.
boolean	isStateful() Returns true if the engine has state and, therefore, should be stored in the HttpSession.
boolean	service(RequestContext context) Method invoked from the ApplicationServlet to perform processing of the request.
void	setLocale(Locale value) Changes the engine's locale.
void	setVisit(Object value) Allows the visit object to be removed; typically done when "shutting down" a user's session (by setting the visit to null).

Field Detail

HOME_PAGE

static final String HOME_PAGE

The name ("Home") of the default page presented when a user first accesses the application.

See Also:

HomeService, Constant Field Values

EXCEPTION_PAGE

static final String EXCEPTION_PAGE

The name ("Exception") of the page used for reporting exceptions.

Such a page must have a writable JavaBeans property named 'exception' of type java.lang.Throwable.

See Also:

Constant Field Values

STALE_LINK_PAGE

static final String STALE_LINK_PAGE

The name ("StaleLink") of the page used for reporting stale links.

The page must implement a writeable JavaBeans proeprty named 'message' of type String.

See Also:

Constant Field Values

STALE_SESSION_PAGE

static final String STALE_SESSION_PAGE

The name ("StaleSession") of the page used for reporting state sessions.

See Also:

Constant Field Values

Method Detail

getPageRecorder

IPageRecorder getPageRecorder(String pageName,
                              IRequestCycle cycle)

Returns a recorder for a page. Returns null if the page recorder has not been created yet.

See Also:

createPageRecorder(String, IRequestCycle)

forgetPage

void forgetPage(String name)

Forgets changes to the named page by discarding the page recorder for the page. This is used when transitioning from one part of an application to another. All property changes for the page are lost.

This should be done if the page is no longer needed or relevant, otherwise the properties for the page will continue to be recorded by the engine, which is wasteful (especially if clustering or failover is employed on the application).

Throws an ApplicationRuntimeException if there are uncommitted changes for the recorder (in the current request cycle).

getLocale

Locale getLocale()

Returns the locale for the engine. This locale is used when selecting templates and assets.

setLocale

void setLocale(Locale value)

Changes the engine's locale. Any subsequently loaded pages will be in the new locale (though pages already loaded stay in the old locale). Generally, you should render a new page after changing the locale, to show that the locale has changed.

createPageRecorder

IPageRecorder createPageRecorder(String pageName,
                                 IRequestCycle cycle)

Creates a new page recorder for the named page.

getPageSource

IPageSource getPageSource()

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

getService

IEngineService getService(String name)

Gets the named service, or throws an ApplicationRuntimeException if the application can't provide the named server.

The object returned has a short lifecycle (it isn't serialized with the engine). Repeated calls with the same name are not guarenteed to return the same object, especially in different request cycles.

getServletPath

String getServletPath()

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.

getContextPath

String getContextPath()

Returns the context path, a string which is prepended to the names of any assets or servlets. This may be the empty string, but won't be null.

This value is obtained from HttpServletRequest.getContextPath().

getSpecification

IApplicationSpecification getSpecification()

Returns the application specification that defines the application and its pages.

getSpecificationSource

ISpecificationSource getSpecificationSource()

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

See Also:

AbstractEngine.createSpecificationSource(RequestContext)

getTemplateSource

ITemplateSource getTemplateSource()

Returns the source for HTML templates.

See Also:

AbstractEngine.createTemplateSource(RequestContext)

service

boolean service(RequestContext context)
                throws ServletException,
                       IOException

Method invoked from the ApplicationServlet to perform processing of the request. In release 3.0, this has become more of a dirty flag, indicating if any state stored by the engine instance itself has changed.

Returns:

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

Throws:

ServletException

IOException

getResourceResolver

IResourceResolver getResourceResolver()

Returns an object that can resolve resources and classes.

getVisit

Object getVisit()

Returns the visit object, an object that represents the client's visit to the application. This is where most server-side state is stored (with the exception of persistent page properties).

Returns the visit, if it exists, or null if it has not been created.

getVisit

Object getVisit(IRequestCycle cycle)

Returns the visit object, creating it if necessary.

setVisit

void setVisit(Object value)

Allows the visit object to be removed; typically done when "shutting down" a user's session (by setting the visit to null).

getGlobal

Object getGlobal()

Returns the globally shared application object. The global object is stored in the servlet context and shared by all instances of the engine for the same application (within the same JVM; the global is not shared between nodes in a cluster).

Returns the global object, if it exists, or null if not defined.

Since:

2.3

isResetServiceEnabled

boolean isResetServiceEnabled()

Returns true if the application allows the reset service.

Since:

0.2.9

getScriptSource

IScriptSource getScriptSource()

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

Since:

1.0.2

isStateful

boolean isStateful()

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).

Since:

1.0.2

getComponentMessagesSource

IComponentMessagesSource getComponentMessagesSource()

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

Since:

2.0.4

See Also:

AbstractEngine.createComponentStringsSource(RequestContext)

getDataSqueezer

DataSqueezer getDataSqueezer()

Returns a shared instance of DataSqueezer.

Since:

2.2

See Also:

AbstractEngine.createDataSqueezer()

getPropertySource

IPropertySource getPropertySource()

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)

Since:

2.3

See Also:

AbstractEngine.createPropertySource(RequestContext)

getPool

Pool getPool()

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.

Since:

3.0

See Also:

AbstractEngine.createPool(RequestContext)

getComponentClassEnhancer

IComponentClassEnhancer getComponentClassEnhancer()

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

Since:

3.0

See Also:

AbstractEngine.createComponentClassEnhancer(RequestContext)

getOutputEncoding

String getOutputEncoding()

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

Since:

3.0

getResourceChecksumSource

ResourceChecksumSource getResourceChecksumSource()

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

Since:

3.0.3