org.apache.tapestry.services
Interface ResponseBuilder

All Known Implementing Classes:

DefaultResponseBuilder, DojoAjaxResponseBuilder, JSONResponseBuilder

public interface ResponseBuilder

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

Author:

jkuhnert

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	SCRIPT_TYPE

Method Summary

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.
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	isBodyScriptAllowed(IComponent target) Determines if the specified component should have its javascript body added to the response.
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	isExternalScriptAllowed(IComponent target) Determines if the specified component should have its javascript external resource scripts added to the response.
boolean	isImageInitializationAllowed(IComponent target) Determines if the specified component should have any asset image URL references embedded in the response.
boolean	isInitializationScriptAllowed(IComponent target) Determines if the specified component should have its javascript initialization added to 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, 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, String script) Writes any javascript that should only execute after all other items on a page have completed rendering.

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

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:

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

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.

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.

isBodyScriptAllowed

boolean isBodyScriptAllowed(IComponent target)

Determines if the specified component should have its javascript body added to the response.

Parameters:

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

Returns:

True if the component script should be allowed.

isInitializationScriptAllowed

boolean isInitializationScriptAllowed(IComponent target)

Determines if the specified component should have its javascript initialization added to the response.

Parameters:

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

Returns:

True if the component script should be allowed.

isExternalScriptAllowed

boolean isExternalScriptAllowed(IComponent target)

Determines if the specified component should have its javascript external resource scripts added to the response.

Parameters:

target - The component to check for inclusion/exclusion.

Returns:

True if external scripts from this component should be added to the response.