com.primix.tapestry
Interface IEngine

All Known Implementing Classes:
AbstractEngine

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,v 1.14 2001/08/15 21:28:10 hship Exp $
Author:
Howard Ship

Field Summary
static java.lang.String EXCEPTION_PAGE
          The name ("Exception") of the page used for reporting exceptions.
static java.lang.String HOME_PAGE
          The name ("Home") of the default page presented when a user first accesses the application.
static java.lang.String STALE_LINK_PAGE
          The name ("StaleLink") of the page used for reporting stale links.
static java.lang.String STALE_SESSION_PAGE
          The name ("StaleSession") of the page used for reporting state sessions.
 
Method Summary
 IPageRecorder createPageRecorder(java.lang.String pageName, IRequestCycle cycle)
          Creates a new page recorder for the named page.
 void forgetPage(java.lang.String name)
          Forgets changes to the named page by discarding the page recorder for the page.
 java.lang.String getContextPath()
          Returns the context path, a string which is prepended to the names of any assets or servlets.
 Pool getHelperBeanPool()
          Returns a Pool from which helper objects may be obtained, and to which they should be returned.
 java.util.Locale getLocale()
          Returns the locale for the engine.
 IPageRecorder getPageRecorder(java.lang.String pageName)
          Returns a recorder for a page.
 IPageSource getPageSource()
          Returns the object used to load a page from its specification.
 IResourceResolver getResourceResolver()
          Returns an object that can resolve resources and classes.
 IScriptSource getScriptSource()
          Returns a source for parsed IScripts.
 IEngineService getService(java.lang.String name)
          Gets the named service, or throws an ApplicationRuntimeException if the application can't provide the named server.
 java.lang.String getServletPath()
          Returns the URL path that corresponds to the servlet for the application.
 ApplicationSpecification 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.
 java.lang.Object getVisit()
          Returns the visit object, an object that represents the client's visit to the application.
 java.lang.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(java.util.Locale value)
          Changes the engine's locale.
 void setVisit(java.lang.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

public static final java.lang.String HOME_PAGE
The name ("Home") of the default page presented when a user first accesses the application.

EXCEPTION_PAGE

public static final java.lang.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.


STALE_LINK_PAGE

public static final java.lang.String STALE_LINK_PAGE
The name ("StaleLink") of the page used for reporting stale links.

STALE_SESSION_PAGE

public static final java.lang.String STALE_SESSION_PAGE
The name ("StaleSession") of the page used for reporting state sessions.
Method Detail

forgetPage

public void forgetPage(java.lang.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

public java.util.Locale getLocale()
Returns the locale for the engine. This locale is used when selecting templates and assets.

setLocale

public void setLocale(java.util.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.

getPageRecorder

public IPageRecorder getPageRecorder(java.lang.String pageName)
Returns a recorder for a page. Returns null if the page record has not been created yet.
See Also:
createPageRecorder(String, IRequestCycle)

createPageRecorder

public IPageRecorder createPageRecorder(java.lang.String pageName,
                                        IRequestCycle cycle)
Creates a new page recorder for the named page.

getPageSource

public IPageSource getPageSource()
Returns the object used to load a page from its specification.

getService

public IEngineService getService(java.lang.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

public java.lang.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

public java.lang.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

public ApplicationSpecification getSpecification()
Returns the application specification that defines the application and its pages.

getSpecificationSource

public ISpecificationSource getSpecificationSource()
Returns the source of all component specifications for the application. The source is shared between sessions.

getTemplateSource

public ITemplateSource getTemplateSource()
Returns the source for HTML templates.

service

public boolean service(RequestContext context)
                throws ServletException,
                       java.io.IOException
Method invoked from the ApplicationServlet to perform processing of the request. The return value for this method indicates whether the state of the engine could possibly change during processing; in most cases this is true. In a few possible cases, this is false. The ApplicationServlet sometimes performs extra work to ensure that the engine is properly replicated in a clustering environment; if this method returns false, it can skip that extra work.

getResourceResolver

public IResourceResolver getResourceResolver()
Returns an object that can resolve resources and classes.

getVisit

public java.lang.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

public java.lang.Object getVisit(IRequestCycle cycle)
Returns the visit object, creating it if necessary.

setVisit

public void setVisit(java.lang.Object value)
Allows the visit object to be removed; typically done when "shutting down" a user's session (by setting the visit to null).

isResetServiceEnabled

public boolean isResetServiceEnabled()
Returns true if the application allows the reset service.
Since:
0.2.9

getScriptSource

public IScriptSource getScriptSource()
Returns a source for parsed IScripts. The source is typically shared between all sessions.
Since:
1.0.2

isStateful

public 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

getHelperBeanPool

public Pool getHelperBeanPool()
Returns a Pool from which helper objects may be obtained, and to which they should be returned. The pool is keyed on class name.
Since:
1.0.4