|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.tapestry.engine.AbstractEngine
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 ITemplateSource
,ISpecificationSource
,
IScriptSource
and IComponentMessagesSource
stored 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 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. |
Field Summary | |
static java.lang.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,
java.lang.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()
Returns an object that can resolve resources and classes. |
DataSqueezer |
getDataSqueezer()
|
java.lang.Object |
getGlobal()
Returns the global object for the application. |
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. |
java.util.Locale |
getLocale()
Returns the locale for the engine. |
java.lang.String |
getOutputEncoding()
Returns the encoding to be used to generate the responses and accept the requests. |
IPropertySource |
getPropertySource()
Returns a IPropertySource that should be used to obtain
configuration data. |
IScriptSource |
getScriptSource()
Returns a source for parsed IScript s. |
IEngineService |
getService(java.lang.String name)
Returns a service with the given name. |
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. |
java.lang.Object |
getVisit()
Gets the visit object from the ApplicationStateManager , creating it if it does not
already exist. |
java.lang.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(java.lang.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(java.lang.String reportTitle,
java.lang.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(java.util.Locale value)
Changes the locale for the engine. |
void |
setVisit(java.lang.Object visit)
Allows the visit object to be removed; typically done when "shutting down" a user's session (by setting the visit to null). |
java.lang.String |
toString()
Generates a description of the instance. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final java.lang.String VISIT_CLASS_PROPERTY_NAME
Constructor Detail |
public AbstractEngine()
Method Detail |
protected void activateExceptionPage(IRequestCycle cycle, java.lang.Throwable cause)
ExceptionPresenter
public void reportException(java.lang.String reportTitle, java.lang.Throwable ex)
System.err
.
RequestExceptionReporter
protected void cleanupAfterRequest(IRequestCycle cycle)
public java.util.Locale getLocale()
ApplicationServlet
but may be updated by the application.
getLocale
in interface IEngine
public IEngineService getService(java.lang.String name)
getService
in interface IEngine
Infrastructure.getServiceMap()
,
ServiceMap
public IApplicationSpecification getSpecification()
IEngine
getSpecification
in interface IEngine
Infrastructure.getApplicationSpecification()
public ISpecificationSource getSpecificationSource()
IEngine
getSpecificationSource
in interface IEngine
Infrastructure.getSpecificationSource()
protected void redirect(java.lang.String pageName, IRequestCycle cycle, org.apache.hivemind.ApplicationRuntimeException exception) throws java.io.IOException
java.io.IOException
public void renderResponse(IRequestCycle cycle) throws java.io.IOException
ResponseRenderer.renderResponse(IRequestCycle)
.
java.io.IOException
public void service(WebRequest request, WebResponse response) throws java.io.IOException
service
in interface WebRequestServicer
java.io.IOException
protected void handlePageRedirectException(IRequestCycle cycle, PageRedirectException exception) throws java.io.IOException
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.
java.io.IOException
protected void handleStaleLinkException(IRequestCycle cycle, StaleLinkException exception) throws java.io.IOException
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.
java.io.IOException
protected void handleStaleSessionException(IRequestCycle cycle, StaleSessionException exception) throws java.io.IOException
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).
java.io.IOException
public void setLocale(java.util.Locale value)
setLocale
in interface IEngine
public org.apache.hivemind.ClassResolver getClassResolver()
IEngine
getClassResolver
in interface IEngine
Infrastructure.getClassResolver()
public java.lang.String toString()
#extendDescription(ToStringBuilder)
to fill in details about the instance.
#extendDescription(ToStringBuilder)
public java.lang.Object getVisit()
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.
getVisit
in interface IEngine
public void setVisit(java.lang.Object visit)
IEngine
setVisit
in interface IEngine
public java.lang.Object getVisit(IRequestCycle cycle)
ApplicationStateManager
, which will create it as
necessary.
getVisit
in interface IEngine
public boolean getHasVisit()
public java.lang.Object getGlobal()
#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.
getGlobal
in interface IEngine
public IScriptSource getScriptSource()
IEngine
IScript
s. The source is shared
between all sessions.
getScriptSource
in interface IEngine
public ListenerMap getListeners()
protected void handleRedirectException(IRequestCycle cycle, RedirectException redirectException)
RedirectException
is thrown during the processing of a request.
org.apache.hivemind.ApplicationRuntimeException
- if an IOException
,ServletException
is thrown by the redirect,
or if no RequestDispatcher
can be found for local resource.public DataSqueezer getDataSqueezer()
Infrastructure.getDataSqueezer()
public IPropertySource getPropertySource()
IEngine
IPropertySource
that should be used to obtain
configuration data. The returned source represents a search path that includes (at a
minimum):
ApplicationSpecification
web.xml
deployment
descriptor)
web.xml
)
-D
JVM command line parameter)
getPropertySource
in interface IEngine
org.apache.tapestry.engine.AbstractEngine#createPropertySource(RequestContext)
public Infrastructure getInfrastructure()
IEngine
Infrastructure
object, a central
registry of key HiveMind services used by Tapestry.
getInfrastructure
in interface IEngine
public java.lang.String getOutputEncoding()
IEngine
getOutputEncoding
in interface IEngine
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |