org.apache.tapestry.services
Interface ResponseBuilder

All Superinterfaces:

IScriptProcessor, PageRenderSupport

All Known Implementing Classes:

DefaultResponseBuilder, DojoAjaxResponseBuilder, JSONResponseBuilder, PrototypeResponseBuilder

public interface ResponseBuilder
extends PageRenderSupport

Represents the service responsible for managing all content output that is sent to the client. In the case of normal http responses this management would inlude handing out IMarkupWriter instances to render components with, as well as managing any javascript written to the output using Script templates.

This is a major internal change in terms of the way tapestry renders pages/components. Traditionally a response has been rendered via: IPage.render(writer, cycle); The logic has now changed somewhat, while the IPage.render(writer, cycle) does still happen, this service is the primary invoker of all renders, even nested component bodies. That means that in the majority of cases the ResponseBuilder service is used to invoke IComponent.render() throught the entire render cycle, creating a great deal of flexibility in terms of what can be done to control the output of a given response.

This service was primarily created to help bolster support for more dynamic content responses, such as XHR/JSON/etc - where controlling individual component output (and javascript) becomes very important when managaing client side browser state.

Since:

4.1

Field Summary

static String	BODY_SCRIPT
static String	CONTENT_TYPE The content type of the response that will be returned.
static String	ELEMENT_TYPE The response element type.
static String	ENCODING_KEY Inside a ContentType, the output encoding is called "charset".
static String	EXCEPTION_TYPE The response exception type.
static String	INCLUDE_SCRIPT
static String	INITIALIZATION_SCRIPT
static String	PAGE_TYPE The response element type denoting a brand new page render.
static String	SCRIPT_TYPE

Method Summary

void	addStatusMessage(IMarkupWriter writer, String category, String text) Adds a status message to the current response.
void	beginBodyScript(IMarkupWriter writer, IRequestCycle cycle) Marks the beginning of the core body script.
boolean	contains(IComponent target) Checks if the rendered response contains a particular component.
void	endBodyScript(IMarkupWriter writer, IRequestCycle cycle) Marks the end of the body block being called.
boolean	explicitlyContains(IComponent target) Similar to contains(IComponent), but only returns true if the component has been marked for update directly via an updateComponents property or by calling updateComponent(String) directly.
void	flush() Causes the output stream to be flushed, used primarily in concert with IRequestCycle to sync up flushing of headers to the browser once any page changes have been committed.
IMarkupWriter	getWriter() Returns the IMarkupWriter associated with this response, it may or may not be a NullWriter instance depending on the response type or stage of the render cycle.
IMarkupWriter	getWriter(String id, String type) Gets a write that will output its content in a response element with the given id and type.
boolean	isDynamic() Implementors that manage content writes dynamically (ie DojoAjaxResponseBuilder) should return true to denote that dynamic behaviour is on for a particular response.
boolean	isImageInitializationAllowed(IComponent target) Determines if the specified component should have any asset image URL references embedded in the response.
void	render(IMarkupWriter writer, IRender render, IRequestCycle cycle) Invoked to render a renderable object.
void	renderResponse(IRequestCycle cycle) Renders the response to a client.
void	updateComponent(String id) If the component identified by the specified id isn't already set to be updated, will add it to the response for updating.
void	writeBodyScript(IMarkupWriter writer, IRequestCycle cycle) Invoked by components that know "when" the method should be called.
void	writeBodyScript(IMarkupWriter writer, String script, IRequestCycle cycle) Called after beginBodyScript(IMarkupWriter, IRequestCycle) to write the containing body script.
void	writeExternalScript(IMarkupWriter writer, String url, IRequestCycle cycle) Invoked by PageRenderSupport to write external js package includes.
void	writeImageInitializations(IMarkupWriter writer, String script, String preloadName, IRequestCycle cycle) Intended to be written within the confines of the body script, should be invoked once just after beginBodyScript(IMarkupWriter, IRequestCycle) is called to include any image initializations.
void	writeInitializationScript(IMarkupWriter writer) Invoked by components that know "when" the method should be called.
void	writeInitializationScript(IMarkupWriter writer, String script) Writes any javascript that should only execute after all other items on a page have completed rendering.

Methods inherited from interface org.apache.tapestry.PageRenderSupport

getPreloadedImageReference, getPreloadedImageReference, getPreloadedImageReference

Methods inherited from interface org.apache.tapestry.IScriptProcessor

addBodyScript, addBodyScript, addExternalScript, addExternalScript, addInitializationScript, addInitializationScript, addScriptAfterInitialization, getUniqueString, isBodyScriptAllowed, isExternalScriptAllowed, isInitializationScriptAllowed

Field Detail

ENCODING_KEY

static final String ENCODING_KEY

Inside a ContentType, the output encoding is called "charset".

See Also:

Constant Field Values

CONTENT_TYPE

static final String CONTENT_TYPE

The content type of the response that will be returned.

See Also:

Constant Field Values

ELEMENT_TYPE

static final String ELEMENT_TYPE

The response element type.

See Also:

Constant Field Values

EXCEPTION_TYPE

static final String EXCEPTION_TYPE

The response exception type.

See Also:

Constant Field Values

PAGE_TYPE

static final String PAGE_TYPE

The response element type denoting a brand new page render.

See Also:

Constant Field Values

SCRIPT_TYPE

static final String SCRIPT_TYPE

See Also:

Constant Field Values

BODY_SCRIPT

static final String BODY_SCRIPT

See Also:

Constant Field Values

INCLUDE_SCRIPT

static final String INCLUDE_SCRIPT

See Also:

Constant Field Values

INITIALIZATION_SCRIPT

static final String INITIALIZATION_SCRIPT

See Also:

Constant Field Values

Method Detail

isDynamic

boolean isDynamic()

Implementors that manage content writes dynamically (ie DojoAjaxResponseBuilder) should return true to denote that dynamic behaviour is on for a particular response.

Returns:

Whether or not request is dynamic.

flush

void flush()
           throws IOException

Causes the output stream to be flushed, used primarily in concert with IRequestCycle to sync up flushing of headers to the browser once any page changes have been committed.

Throws:

IOException - During io error.

renderResponse

void renderResponse(IRequestCycle cycle)
                    throws IOException

Renders the response to a client. Handles transitioning logic for setting up page and associated components for response.

Parameters:

cycle - The main request cycle object for this request.

Throws:

IOException - During io error.

render

void render(IMarkupWriter writer,
            IRender render,
            IRequestCycle cycle)

Invoked to render a renderable object. Performs any necessary under the hood type logic involving ajax/json/normal responses, where needed.

Parameters:

writer - The markup writer to use, this may be ignored or swapped out for a different writer depending on the implementation being used.

render - The renderable object to render

cycle - Render request cycle

updateComponent

void updateComponent(String id)

If the component identified by the specified id isn't already set to be updated, will add it to the response for updating. (Only applicable in dynamic responses such as XHR/JSON ).

Parameters:

id - The IComponent id to update.

contains

boolean contains(IComponent target)

Checks if the rendered response contains a particular component. Contains can mean many things. In the instance of a dynamic response it could potentially mean a component explicitly set to be updated - or a component that has a containing component explicitly set to be updated.

Parameters:

target - The component to check containment of.

Returns:

True if response contains the specified component, false otherwise.

explicitlyContains

boolean explicitlyContains(IComponent target)

Similar to contains(IComponent), but only returns true if the component has been marked for update directly via an updateComponents property or by calling updateComponent(String) directly.

IMPORTANT!: This will not return true for components contained by a component marked for update. If you want that kind of behaviour use contains(IComponent).

Parameters:

target - The component to check.

Returns:

True if the component as listed as one to be updated, false otherwise.

writeBodyScript

void writeBodyScript(IMarkupWriter writer,
                     IRequestCycle cycle)

Invoked by components that know "when" the method should be called. Causes all queued up body related javascript data to be written out to the response.

Parameters:

writer - The writer to use . (may / may not be ignored depending on the response type)

cycle - Associated request.

writeInitializationScript

void writeInitializationScript(IMarkupWriter writer)

Invoked by components that know "when" the method should be called. Causes all queued up initialization related javascript data to be written out to the response.

Parameters:

writer - The writer to use . (may / may not be ignored depending on the response type)

writeExternalScript

void writeExternalScript(IMarkupWriter writer,
                         String url,
                         IRequestCycle cycle)

Invoked by PageRenderSupport to write external js package includes. This method will be invoked for each external script requesting inclusion in the response. These will typically be written out as .

Parameters:

writer - The markup writer to use, this may be ignored or swapped out for a different writer depending on the implementation being used.

url - The absolute url to the .js package to be included.

cycle - The associated request.

beginBodyScript

void beginBodyScript(IMarkupWriter writer,
                     IRequestCycle cycle)

Marks the beginning of the core body script.

Parameters:

writer - The markup writer to use, this may be ignored or swapped out for a different writer depending on the implementation being used.

cycle - The associated request.

writeImageInitializations

void writeImageInitializations(IMarkupWriter writer,
                               String script,
                               String preloadName,
                               IRequestCycle cycle)

Intended to be written within the confines of the body script, should be invoked once just after beginBodyScript(IMarkupWriter, IRequestCycle) is called to include any image initializations. This method should only be called if there are actually images that need pre-initialization. Ie in many instances it will not be called at all.

Parameters:

writer - The markup writer to use, this may be ignored or swapped out for a different writer depending on the implementation being used.

script - The non null value of the script images to include.

preloadName - The global variable name to give to the preloaded images array.

cycle - The associated request.

writeBodyScript

void writeBodyScript(IMarkupWriter writer,
                     String script,
                     IRequestCycle cycle)

Called after beginBodyScript(IMarkupWriter, IRequestCycle) to write the containing body script. This method may not be called at all if there is no js body to write into the response.

Parameters:

writer - The markup writer to use, this may be ignored or swapped out for a different writer depending on the implementation being used.

script - The script to write into the body response.

cycle - The associated request.

endBodyScript

void endBodyScript(IMarkupWriter writer,
                   IRequestCycle cycle)

Marks the end of the body block being called. This method will always be called if beginBodyScript(IMarkupWriter, IRequestCycle) was previously called.

Parameters:

writer - The markup writer to use, this may be ignored or swapped out for a different writer depending on the implementation being used.

cycle - The associated request.

writeInitializationScript

void writeInitializationScript(IMarkupWriter writer,
                               String script)

Writes any javascript that should only execute after all other items on a page have completed rendering. This is typically implemented via wrapping the executing of the code to some sort of window.onload event, but will vary depending on the implementation of the builder being used. This method will ~only~ be called if there is any queued intialization script to write.

Parameters:

writer - The markup writer to use, this may be ignored or swapped out for a different writer depending on the implementation being used.

script - The initialzation script to write.

getWriter

IMarkupWriter getWriter()

Returns the IMarkupWriter associated with this response, it may or may not be a NullWriter instance depending on the response type or stage of the render cycle. (specifically during rewind)

Returns:

A validly writable markup writer, even if the content is sometimes ignored.

getWriter

IMarkupWriter getWriter(String id,
                        String type)

Gets a write that will output its content in a response element with the given id and type.

Parameters:

id - The response element id to give writer.

type - Optional - If specified will give the response element a type attribute.

Returns:

A valid IMarkupWriter instance to write content to.

isImageInitializationAllowed

boolean isImageInitializationAllowed(IComponent target)

Determines if the specified component should have any asset image URL references embedded in the response.

Parameters:

target - The component to allow/disallow image initialization script content from.

Returns:

True if the component script should be allowed.

addStatusMessage

void addStatusMessage(IMarkupWriter writer,
                      String category,
                      String text)

Adds a status message to the current response.

Parameters:

writer - The markup writer to use, this may be ignored or swapped out for a different writer depending on the implementation being used.

category - Allows setting a category that best describes the type of the status message, i.e. info, error, e.t.c.

text - The status message.