Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> apache >> [ tapestry overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.apache.tapestry.IRequestCycle JAVADOC | Sourc code of org.apache.tapestry.IRequestCycle SOURCE | Download org.apache.tapestry.IRequestCycle DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.apache.tapestry
Interface IRequestCycle  view IRequestCycle download IRequestCycle.java

public interface IRequestCycle

Controller object that manages a single request cycle. A request cycle is one 'hit' on the web server. In the case of a Tapestry application, this will involve:

Mixed in with this is:

A request cycle is broken up into two phases. The rewind phase is optional, as it tied to org.apache.tapestry.link.ActionLink or org.apache.tapestry.form.Form components. In the rewind phase, a previous page render is redone (discarding output) until a specific component of the page is reached. This rewinding ensures that the page is restored to the exact state it had when the URL for the request cycle was generated, taking into account the dynamic nature of the page (org.apache.tapestry.components.Foreach, org.apache.tapestry.components.Conditional, etc.). Once this component is reached, it can notify its IActionListener. The listener has the ability to update the state of any pages and select a new result page.

Following the rewind phase is the render phase. During the render phase, a page is actually rendered and output sent to the client web browser.

Method Summary
 void activate(IPage page)
          Sets the active page for the request.
 void activate(java.lang.String name)
          A convienience for invoking activate(IPage) 55 .
 void cleanup()
          Invoked after the request cycle is no longer needed, to release any resources it may have.
 void commitPageChanges()
          Invoked just before rendering the response page to get all page recorders touched in this request cycle to commit their changes (save them to persistant storage).
 void discardPage(java.lang.String name)
          Much like IEngine.forgetPage(String) 55 , but the page stays active and can even record changes, until the end of the request cycle, at which point it is discarded (and any recorded changes are lost).
 java.lang.String encodeURL(java.lang.String URL)
          Passes the String through HttpServletResponse.encodeURL(java.lang.String)>HttpServletResponse.encodeURL(java.lang.String) 55 , which ensures that the session id is encoded in the URL (if necessary).
 java.lang.Object getAttribute(java.lang.String name)
          Retrieves a previously stored attribute, returning null if not found.
 IEngine getEngine()
          Returns the engine which is processing this request cycle.
 org.apache.tapestry.engine.IMonitor getMonitor()
           
 java.lang.String getNextActionId()
          Returns the next action id.
 IPage getPage()
          Identifies the active page, the page which will ultimately render the response.
 IPage getPage(java.lang.String name)
          Returns the page with the given name.
 org.apache.tapestry.request.RequestContext getRequestContext()
           
 org.apache.tapestry.engine.IEngineService getService()
          Returns the service which initiated this request cycle.
 java.lang.Object[] getServiceParameters()
          Returns parameters previously stored by setServiceParameters(Object[]) 55 .
 boolean isRewinding()
          Returns true if the context is being used to rewind a prior state of the page.
 boolean isRewound(IComponent component)
          Checks to see if the current action id matches the target action id.
 void removeAttribute(java.lang.String name)
          Removes a previously stored attribute, if one with the given name exists.
 void renderPage(IMarkupWriter writer)
          Renders the given page.
 void rewindForm(IForm form, java.lang.String targetActionId)
          Used by forms to perform a partial rewind so as to respond to the form submission (using the direct service).
 void rewindPage(java.lang.String targetActionId, IComponent targetComponent)
          Rewinds a page and executes some form of action when the component with the specified action id is reached.
 void setAttribute(java.lang.String name, java.lang.Object value)
          Allows a temporary object to be stored in the request cycle, which allows otherwise unrelated objects to communicate.
 void setPage(IPage page)
          Deprecated. To be removed in 3.1. Use activate(IPage) 55 .
 void setPage(java.lang.String name)
          Deprecated. To be removed in 3.1. Use activate(String) 55 .
 void setServiceParameters(java.lang.Object[] parameters)
          Invoked by a service to store an array of application-specific parameters.
 

Method Detail

cleanup

public void cleanup()
Invoked after the request cycle is no longer needed, to release any resources it may have. This includes releasing any loaded pages back to the page source.

encodeURL

public java.lang.String encodeURL(java.lang.String URL)
Passes the String through HttpServletResponse.encodeURL(java.lang.String)>HttpServletResponse.encodeURL(java.lang.String) 55 , which ensures that the session id is encoded in the URL (if necessary).

getEngine

public IEngine getEngine()
Returns the engine which is processing this request cycle.

getAttribute

public java.lang.Object getAttribute(java.lang.String name)
Retrieves a previously stored attribute, returning null if not found. Attributes allow components to locate each other; primarily they allow a wrapped component to locate a component which wraps it.

getMonitor

public org.apache.tapestry.engine.IMonitor getMonitor()

getNextActionId

public java.lang.String getNextActionId()
Returns the next action id. ActionLink ids are used to identify different actions on a page (URLs that are related to dynamic page state).

getPage

public IPage getPage()
Identifies the active page, the page which will ultimately render the response.

getPage

public IPage getPage(java.lang.String name)
Returns the page with the given name. If the page has been previously loaded in the current request cycle, that page is returned. Otherwise, the engine's page loader is used to load the page.

getRequestContext

public org.apache.tapestry.request.RequestContext getRequestContext()

isRewinding

public boolean isRewinding()
Returns true if the context is being used to rewind a prior state of the page. This is only true when there is a target action id.

isRewound

public boolean isRewound(IComponent component)
                  throws StaleLinkException
Checks to see if the current action id matches the target action id. Returns true only if they match. Returns false if there is no target action id (that is, during page rendering).

If theres a match on action id, then the component is compared against the target component. If there's a mismatch then a StaleLinkException is thrown.

removeAttribute

public void removeAttribute(java.lang.String name)
Removes a previously stored attribute, if one with the given name exists.

renderPage

public void renderPage(IMarkupWriter writer)
Renders the given page. Applications should always use this method to render the page, rather than directly invoking IRender.render(IMarkupWriter, IRequestCycle) 55 since the request cycle must perform some setup before rendering.

rewindPage

public void rewindPage(java.lang.String targetActionId,
                       IComponent targetComponent)
Rewinds a page and executes some form of action when the component with the specified action id is reached.

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object value)
Allows a temporary object to be stored in the request cycle, which allows otherwise unrelated objects to communicate. This is similar to HttpServletRequest.setAttribute(), except that values can be changed and removed as well.

This is used by components to locate each other. A component, such as org.apache.tapestry.html.Body, will write itself under a well-known name into the request cycle, and components it wraps can locate it by that name.

setPage

public void setPage(IPage page)
Deprecated. To be removed in 3.1. Use activate(IPage) 55 .

Sets the page to be rendered. This is called by a component during the rewind phase to specify an alternate page to render during the response phase.

setPage

public void setPage(java.lang.String name)
Deprecated. To be removed in 3.1. Use activate(String) 55 .

Sets the page to be rendered. This is called by a component during the rewind phase to specify an alternate page to render during the response phase.

commitPageChanges

public void commitPageChanges()
Invoked just before rendering the response page to get all page recorders touched in this request cycle to commit their changes (save them to persistant storage).

getService

public org.apache.tapestry.engine.IEngineService getService()
Returns the service which initiated this request cycle. This may return null (very early during the request cycle) if the service has not yet been determined.

Since:
1.0.1

rewindForm

public void rewindForm(IForm form,
                       java.lang.String targetActionId)
Used by forms to perform a partial rewind so as to respond to the form submission (using the direct service).

Since:
1.0.2

discardPage

public void discardPage(java.lang.String name)
Much like IEngine.forgetPage(String) 55 , but the page stays active and can even record changes, until the end of the request cycle, at which point it is discarded (and any recorded changes are lost). This is used in certain rare cases where a page has persistent state but is being renderred "for the last time".

Since:
2.0.2

setServiceParameters

public void setServiceParameters(java.lang.Object[] parameters)
Invoked by a service to store an array of application-specific parameters. These can later be retrieved (typically, by an application-specific listener method) by invoking getServiceParameters() 55 .

Through release 2.1, parameters was of type String[]. This is an incompatible change in 2.2.

Since:
2.0.3

getServiceParameters

public java.lang.Object[] getServiceParameters()
Returns parameters previously stored by setServiceParameters(Object[]) 55 .

Through release 2.1, the return type was String[]. This is an incompatible change in 2.2.

Since:
2.0.3

activate

public void activate(java.lang.String name)
A convienience for invoking activate(IPage) 55 . Invokes getPage(String) 55 to get an instance of the named page.

Since:
3.0

activate

public void activate(IPage page)
Sets the active page for the request. The active page is the page which will ultimately render the response. The activate page is typically set by the service. Frequently, the active page is changed (from a listener method) to choose an alternate page to render the response).

IPage.validate(IRequestCycle) 55 is invoked on the page to be activated. PageRedirectException is caught and the page specified in the exception will be the active page instead (that is, a page may "pass the baton" to another page using the exception). The new page is also validated. This continues until a page does not throw PageRedirectException.

Validation loops can occur, where page A redirects to page B and then page B redirects back to page A (possibly with intermediate steps). This is detected and results in an ApplicationRuntimeException.

Since:
3.0
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> apache >> [ tapestry overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.apache.tapestry.IRequestCycle JAVADOC | Sourc code of org.apache.tapestry.IRequestCycle SOURCE | Download org.apache.tapestry.IRequestCycle DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD