|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.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 3.1. 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 |
DEFAULT_OUTPUT_ENCODING
The default encoding that will be used when generating the output. |
static java.lang.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 |
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,
ResponseOutputStream output,
java.lang.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. |
abstract java.util.Collection |
getActivePageNames()
Implemented by subclasses to return the names of the active pages (pages for which recorders exist). |
org.apache.hivemind.ClassResolver |
getClassResolver()
Returns an object that can resolve resources and classes. |
DataSqueezer |
getDataSqueezer()
|
protected java.lang.String |
getDefaultOutputEncoding()
The encoding to be used if none has been defined using the output encoding property. |
protected java.lang.String |
getExceptionPageName()
|
java.lang.Object |
getGlobal()
Returns the global object for the application. |
boolean |
getHasVisit()
|
Infrastructure |
getInfrastructure()
|
ListenerMap |
getListeners()
Allows subclasses to include listener methods easily. |
java.util.Locale |
getLocale()
Returns the locale for the engine. |
IMonitor |
getMonitor(RequestContext context)
Overriden in subclasses that support monitoring. |
java.lang.String |
getOutputEncoding()
Returns the encoding to be used to generate the servlet responses and accept the servlet 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. |
protected java.lang.String |
getStaleLinkPageName()
|
protected java.lang.String |
getStaleSessionPageName()
|
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(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 . |
protected void |
redirect(java.lang.String pageName,
IRequestCycle cycle,
ResponseOutputStream out,
org.apache.hivemind.ApplicationRuntimeException exception)
Invoked, typically, when an exception occurs while servicing the request. |
void |
renderResponse(IRequestCycle cycle,
ResponseOutputStream output)
Delegates to ResponseRenderer.renderResponse(IRequestCycle, ResponseOutputStream) . |
void |
reportException(java.lang.String reportTitle,
java.lang.Throwable ex)
Writes a detailed report of the exception to System.err . |
boolean |
service(RequestContext context)
Delegate method for the servlet. |
void |
setLocale(java.util.Locale value)
Changes the locale for the engine. |
protected void |
setupForRequest(RequestContext context)
Invoked from service(RequestContext) to ensure that the engine's instance variables
are setup. |
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 OUTPUT_ENCODING_PROPERTY_NAME
public static final java.lang.String DEFAULT_OUTPUT_ENCODING
public static final java.lang.String VISIT_CLASS_PROPERTY_NAME
Constructor Detail |
public AbstractEngine()
Method Detail |
protected void activateExceptionPage(IRequestCycle cycle, ResponseOutputStream output, java.lang.Throwable cause) throws javax.servlet.ServletException
If the render throws an exception, then copious output is sent to System.err
and a ServletException
is thrown.
javax.servlet.ServletException
public void reportException(java.lang.String reportTitle, java.lang.Throwable ex)
System.err
.
protected abstract void cleanupAfterRequest(IRequestCycle cycle)
public java.util.Locale getLocale()
ApplicationServlet
but may be updated by the application.
getLocale
in interface IEngine
public IMonitor getMonitor(RequestContext context)
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.
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, ResponseOutputStream out, org.apache.hivemind.ApplicationRuntimeException exception) throws java.io.IOException, javax.servlet.ServletException
java.io.IOException
javax.servlet.ServletException
public void renderResponse(IRequestCycle cycle, ResponseOutputStream output) throws javax.servlet.ServletException, java.io.IOException
ResponseRenderer.renderResponse(IRequestCycle, ResponseOutputStream)
.
javax.servlet.ServletException
java.io.IOException
public boolean service(RequestContext context) throws javax.servlet.ServletException, java.io.IOException
service
in interface IEngine
javax.servlet.ServletException
java.io.IOException
protected void handlePageRedirectException(PageRedirectException ex, IRequestCycle cycle, ResponseOutputStream output) throws java.io.IOException, javax.servlet.ServletException
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.
java.io.IOException
javax.servlet.ServletException
protected void handleStaleLinkException(StaleLinkException ex, IRequestCycle cycle, ResponseOutputStream output) throws java.io.IOException, javax.servlet.ServletException
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.
java.io.IOException
javax.servlet.ServletException
protected void handleStaleSessionException(StaleSessionException ex, IRequestCycle cycle, ResponseOutputStream output) throws java.io.IOException, javax.servlet.ServletException
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.
java.io.IOException
javax.servlet.ServletException
public void setLocale(java.util.Locale value)
setLocale
in interface IEngine
protected void setupForRequest(RequestContext context)
service(RequestContext)
to ensure that the engine's instance variables
are setup. This allows the application a chance to restore 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.
Subclasses should invoke this implementation first, then perform their own setup.
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.
toString
in class java.lang.Object
#extendDescription(ToStringBuilder)
public abstract java.util.Collection getActivePageNames()
public java.lang.Object getVisit()
ApplicationStateManager
, creating it if it does not
already exist.
As of Tapestry 3.1, 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 ex)
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)
protected java.lang.String getExceptionPageName()
protected java.lang.String getStaleLinkPageName()
protected java.lang.String getStaleSessionPageName()
protected java.lang.String getDefaultOutputEncoding()
public java.lang.String getOutputEncoding()
getOutputEncoding
in interface IEngine
IEngine.getOutputEncoding()
public Infrastructure getInfrastructure()
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |