|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.primix.tapestry.engine.AbstractEngine
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
and ISpecificationSource
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 SimpleEngine
)
is used without subclassing. Instead, a
visit object is specified. To facilitate this, the application specification
may include a property, com.primix.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 parameters (typically only used during development):
Parameter | Description |
---|---|
com.primix.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() . |
com.primix.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 | |
protected static java.lang.String |
HELPER_BEAN_POOL_NAME
Servlet context attribute name for the Pool used to obtain
helper beans. |
protected static java.lang.String |
PAGE_SOURCE_NAME
Servlet context attribute name for the IPageSource
instance. |
protected PageSource |
pageSource
The source for pages, which acts as a pool, but is capable of creating pages as needed. |
protected static java.lang.String |
SCRIPT_SOURCE_NAME
The name of the context attribute for the IScriptSource instance. |
protected ApplicationSpecification |
specification
The specification for the application, which lives in the ServletContext . |
protected static java.lang.String |
SPECIFICATION_SOURCE_NAME
Servlet context attribute name for the default ISpecificationSource
instance. |
protected ISpecificationSource |
specificationSource
The source for component specifications, stored in the ServletContext (like templateSource ). |
protected static java.lang.String |
TEMPLATE_SOURCE_NAME
Servlet context attribute name for the default ITemplateSource
instance. |
protected ITemplateSource |
templateSource
The source for template data. |
static java.lang.String |
VISIT_CLASS_PROPERTY_NAME
The name of the application specification property used to specify the class of the visit object. |
Fields inherited from interface com.primix.tapestry.IEngine |
EXCEPTION_PAGE, HOME_PAGE, STALE_LINK_PAGE, STALE_SESSION_PAGE |
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. |
protected void |
cleanupEngine()
Invoked when the engine is removed from the HttpSession i.e.,
because the sesssion timed out or was explicitly invalidated. |
protected void |
clearCachedData()
Discards all cached pages, component specifications and templates. |
protected IEngineService |
constructService(java.lang.String name)
Invoked by getService(String) to construct a named service. |
protected java.lang.Object |
createVisit(IRequestCycle cycle)
Invoked to lazily create a new visit object when it is first referenced (by getVisit(IRequestCycle) ). |
void |
extendDescription(java.lang.StringBuffer buffer)
Extends the description of the class generated by toString() . |
abstract java.util.Collection |
getActivePageNames()
Implemented by subclasses to return the names of the active pages (pages for which recorders exist). |
java.lang.String |
getContextPath()
Returns the context path, the prefix to apply to any URLs so that they are recognizing as belonging to the Servlet 2.2 context. |
boolean |
getHasVisit()
|
Pool |
getHelperBeanPool()
Returns a Pool from which helper objects may be obtained,
and to which they should be returned. |
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. |
IPageSource |
getPageSource()
Returns the object used to load a page from its specification. |
IResourceResolver |
getResourceResolver()
Returns an object which can find resources and classes. |
IScriptSource |
getScriptSource()
Returns a source for parsed IScript s. |
IEngineService |
getService(java.lang.String name)
Returns a service with the given name, constructing it (via constructService(String) if necessary. |
java.lang.String |
getServletPath()
Returns the URL path that corresponds to the servlet for the application. |
ApplicationSpecification |
getSpecification()
Returns the specification, if available, or null otherwise. |
ISpecificationSource |
getSpecificationSource()
Returns the source of all component specifications for the application. |
ITemplateSource |
getTemplateSource()
Returns the source for HTML templates. |
java.lang.Object |
getVisit()
Gets the visit object, if it has been created already. |
java.lang.Object |
getVisit(IRequestCycle cycle)
Gets the visit object, invoking createVisit(IRequestCycle) to create
it lazily if needed. |
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 |
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. |
void |
readExternal(java.io.ObjectInput in)
Reads the state serialized by writeExternal(ObjectOutput) . |
protected void |
redirect(java.lang.String pageName,
IRequestCycle cycle,
ResponseOutputStream out,
RequestCycleException exception)
Invoked, typically, when an exception occurs while servicing the request. |
protected void |
redirectOut(IRequestCycle cycle,
RedirectException ex)
Invoked when a RedirectException is thrown during the processing of a request. |
protected void |
render(IRequestCycle cycle,
ResponseOutputStream output)
Invoked to render an actual result page (as opposed to a rewind). |
protected void |
reportException(java.lang.String reportTitle,
java.lang.Throwable ex)
Writes a detailed report of the exception to System.err . |
protected 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. |
protected void |
serviceAction(IRequestCycle cycle,
java.lang.String[] serviceContext,
ResponseOutputStream output)
Processes an 'action' URL. |
protected void |
serviceDirect(IRequestCycle cycle,
java.lang.String[] serviceContext,
java.lang.String[] parameters,
ResponseOutputStream output)
Processes a 'direct' URL. |
protected void |
servicePage(IRequestCycle cycle,
java.lang.String[] serviceContext,
ResponseOutputStream output)
Processes a 'page' URL. |
protected void |
serviceReset(IRequestCycle cycle,
java.lang.String[] serviceContext,
ResponseOutputStream output)
Clears the cache of pages, specifications and templates. |
void |
setLocale(java.util.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(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). |
java.lang.String |
toString()
Generates a description of the instance. |
void |
valueBound(HttpSessionBindingEvent event)
Invoked when the application object is stored into the HttpSession . |
void |
valueUnbound(HttpSessionBindingEvent event)
Invoked when the application object is removed from the HttpSession . |
void |
writeExternal(java.io.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 |
Methods inherited from interface com.primix.tapestry.IEngine |
createPageRecorder, forgetPage, getPageRecorder |
Field Detail |
protected transient ApplicationSpecification specification
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.protected transient ITemplateSource templateSource
ServletContext
as a named attribute.
After de-serialization, the application can re-connect to
the template source (or create a new one).protected transient ISpecificationSource specificationSource
ServletContext
(like templateSource
).protected static final java.lang.String SCRIPT_SOURCE_NAME
IScriptSource
instance.
The application's name is appended.public static final java.lang.String VISIT_CLASS_PROPERTY_NAME
protected static final java.lang.String TEMPLATE_SOURCE_NAME
ITemplateSource
instance. The application's name is appended.protected static final java.lang.String SPECIFICATION_SOURCE_NAME
ISpecificationSource
instance. The application's name is appended.protected static final java.lang.String HELPER_BEAN_POOL_NAME
Pool
used to obtain
helper beans. The application's name is appended.protected static final java.lang.String PAGE_SOURCE_NAME
IPageSource
instance. The application's name is appended.protected transient PageSource pageSource
ServletContext
, like templateSource
.Constructor Detail |
public AbstractEngine()
Method Detail |
protected void activateExceptionPage(IRequestCycle cycle, ResponseOutputStream output, java.lang.Throwable cause) throws ServletException
If the render throws an exception, then copious output is sent to
System.err
and a ServletException
is thrown.
protected void reportException(java.lang.String reportTitle, java.lang.Throwable ex)
System.err
.protected abstract void cleanupAfterRequest(IRequestCycle cycle)
protected IEngineService constructService(java.lang.String name)
getService(String)
to construct a named service. This method
should return a new instance of the named service, or null if the
application doesn't implement the named service.
This seems a little awkward, but the idea is to avoid creating the service
object until it is needed, since once created they have the lifecycle of the
application object, which can be quite long. I don't know that its worth
the cycles to create a more involved solution -- for example, extend the
interface so that a pooled service object could be bound temporarily to
a specific instance of the engine. Best to just leave this alone.
Subclasses should overide this method, but must also invoke it to provide the services provided by AbstractEngine:
com.primix.tapestry.enable-reset-service
is true)
public void extendDescription(java.lang.StringBuffer buffer)
toString()
.
If a subclass adds additional instance variables that should be described
in the instance description, it may overide this method. Subclasses
should invoke this implementation first. They should append a space
before each value.toString()
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
. May return null.
The monitor is used to create a RequestCycle
.
This implementation returns null always. Subclasses may overide without invoking it.
TBD: Lifecycle of the monitor ... should there be a commit?
public IPageSource getPageSource()
IEngine
getPageSource
in interface IEngine
public IEngineService getService(java.lang.String name)
constructService(String)
if necessary.getService
in interface IEngine
public java.lang.String getServletPath()
IEngine
IEngineService
that need
to construct URLs for the application. This value will include
the context path.getServletPath
in interface IEngine
public java.lang.String getContextPath()
getContextPath
in interface IEngine
ContextAsset
public ApplicationSpecification getSpecification()
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.
getSpecification
in interface IEngine
public ISpecificationSource getSpecificationSource()
IEngine
getSpecificationSource
in interface IEngine
public ITemplateSource getTemplateSource()
IEngine
getTemplateSource
in interface IEngine
public void readExternal(java.io.ObjectInput in) throws java.io.IOException, java.lang.ClassNotFoundException
writeExternal(ObjectOutput)
.
This always set the stateful flag. By default, a deserialized session is stateful (else, it would not have been serialized).
readExternal
in interface java.io.Externalizable
public void writeExternal(java.io.ObjectOutput out) throws java.io.IOException
Locale.toString()
)
writeExternal
in interface java.io.Externalizable
protected void redirect(java.lang.String pageName, IRequestCycle cycle, ResponseOutputStream out, RequestCycleException exception) throws java.io.IOException, RequestCycleException, ServletException
protected void render(IRequestCycle cycle, ResponseOutputStream output) throws RequestCycleException, ServletException, java.io.IOException
Invokes IRequestCycle.commitPageChanges()
before rendering the
page.
protected void restart(IRequestCycle cycle) throws java.io.IOException
Subclasses should perform their own restart (if necessary, which is rarely) before invoking this implementation.
public boolean service(RequestContext context) throws ServletException, java.io.IOException
service
in interface IEngine
protected void handleStaleLinkException(StaleLinkException ex, IRequestCycle cycle, ResponseOutputStream output) throws java.io.IOException, ServletException, RequestCycleException
service(RequestContext)
if a StaleLinkException
is thrown by the service
. This implementation
invokes
redirect(String, IRequestCycle, ResponseOutputStream, RequestCycleException)
to render the StaleLink 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.
protected void handleStaleSessionException(StaleSessionException ex, IRequestCycle cycle, ResponseOutputStream output) throws java.io.IOException, ServletException, RequestCycleException
service(RequestContext)
if a StaleSessionException
is thrown by the service
. This implementation
invokes
redirect(String, IRequestCycle, ResponseOutputStream, RequestCycleException)
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.
protected void serviceAction(IRequestCycle cycle, java.lang.String[] serviceContext, ResponseOutputStream output) throws RequestCycleException, ServletException, java.io.IOException
IRequestCycle.rewindPage(String, IComponent)
is invoked,
to rewind the page to
the target action id and target component id path,
by going through the motions of
rendering again.
render(IRequestCycle, ResponseOutputStream)
is invoked, to render
the response page.
protected void serviceDirect(IRequestCycle cycle, java.lang.String[] serviceContext, java.lang.String[] parameters, ResponseOutputStream output) throws RequestCycleException, ServletException, java.io.IOException
IDirect
.
IDirect.trigger(IRequestCycle, String[])
is invoked to trigger the
behaviour associated with the component.
render(IRequestCycle,ResponseOutputStream)
is invoked to
render the response page.
protected void servicePage(IRequestCycle cycle, java.lang.String[] serviceContext, ResponseOutputStream output) throws RequestCycleException, ServletException, java.io.IOException
protected void serviceReset(IRequestCycle cycle, java.lang.String[] serviceContext, ResponseOutputStream output) throws RequestCycleException, ServletException, java.io.IOException
Clears the cache of pages, specifications and templates.
protected void clearCachedData()
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 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 final path is available via the getServletPath()
method.
In addition, this method locates and/or creates the:
ITemplateSource
ISpecificationSource
IPageSource
Pool
Subclasses should invoke this implementation first, then perform their own setup.
public Pool getHelperBeanPool()
IEngine
Pool
from which helper objects may be obtained,
and to which they should be returned.
The pool is keyed on class name.getHelperBeanPool
in interface IEngine
public IResourceResolver getResourceResolver()
getResourceResolver
in interface IEngine
public java.lang.String toString()
extendDescription(StringBuffer)
to fill in details about the instance.toString
in class java.lang.Object
extendDescription(StringBuffer)
public void valueBound(HttpSessionBindingEvent event)
HttpSession
. This implementation does nothing.valueBound
in interface HttpSessionBindingListener
public void valueUnbound(HttpSessionBindingEvent event)
HttpSession
.
This occurs when the session times out or is explicitly invalidated
(for example, by the reset or restart services). Invokes
cleanupEngine()
.valueUnbound
in interface HttpSessionBindingListener
protected void cleanupEngine()
HttpSession
i.e.,
because the sesssion timed out or was explicitly invalidated.
Locates all active pages (pages which have been activated) and
invokes IPage.cleanupPage()
on them. This gives
pages a chance to release any long held resources. This primarily
exists so that pages that hold references to stateful session EJBs
can remove those EJBs in a timely manner.
Subclasses may overide this method to clean up any engine-held resources, but should invoke this implementation first.
public boolean isResetServiceEnabled()
isResetServiceEnabled
in interface IEngine
public abstract java.util.Collection getActivePageNames()
public java.lang.Object getVisit()
getVisit
in interface IEngine
public java.lang.Object getVisit(IRequestCycle cycle)
createVisit(IRequestCycle)
to create
it lazily if needed.getVisit
in interface IEngine
public void setVisit(java.lang.Object value)
IEngine
setVisit
in interface IEngine
public boolean getHasVisit()
protected java.lang.Object createVisit(IRequestCycle cycle)
getVisit(IRequestCycle)
). This implementation works
by looking up the name of the class
in the application specification.
Subclasses may want to overide this method if some other means of instantiating a visit object is required.
public IScriptSource getScriptSource()
IEngine
IScript
s. The source is typically
shared between all sessions.getScriptSource
in interface IEngine
public boolean isStateful()
IEngine
isStateful
in interface IEngine
protected void setStateful()
RequestContext
).public ListenerMap getListeners()
protected void redirectOut(IRequestCycle cycle, RedirectException ex) throws RequestCycleException
RedirectException
is thrown during the processing of a request.RequestCycleException
- if an IOException
is thrown by the redirect
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |