org.apache.tapestry.services.impl
Class DojoAjaxResponseBuilder

java.lang.Object
  org.apache.tapestry.services.impl.DojoAjaxResponseBuilder

All Implemented Interfaces:

IScriptProcessor, PageRenderSupport, ResponseBuilder

public class DojoAjaxResponseBuilder
extends Object
implements ResponseBuilder

Main class that handles dojo based ajax responses. These responses are wrapped by an xml document format that segments off invididual component/javascript response types into easy to manage xml elements that can then be interpreted and managed by running client-side javascript.

Field Summary

Fields inherited from interface org.apache.tapestry.services.ResponseBuilder

BODY_SCRIPT, CONTENT_TYPE, ELEMENT_TYPE, ENCODING_KEY, EXCEPTION_TYPE, INCLUDE_SCRIPT, INITIALIZATION_SCRIPT, PAGE_TYPE, SCRIPT_TYPE

Constructor Summary

DojoAjaxResponseBuilder(IRequestCycle cycle, IMarkupWriter writer, List parts)
Creates a builder with a pre-configured IMarkupWriter.

DojoAjaxResponseBuilder(IRequestCycle cycle, IMarkupWriter writer, List parts, List errorPages)
Creates a builder with a pre-configured IMarkupWriter.

DojoAjaxResponseBuilder(IRequestCycle cycle, RequestLocaleManager localeManager, MarkupWriterSource markupWriterSource, WebResponse webResponse, List errorPages, AssetFactory assetFactory, String namespace, IEngineService pageService)
Creates a new response builder with the required services it needs to render the response when renderResponse(IRequestCycle) is called.

Method Summary

void	addBodyScript(IComponent target, String script) Adds scripting code to the main body.
void	addBodyScript(String script) Adds scripting code to the main body.
void	addExternalScript(IComponent target, org.apache.hivemind.Resource resource) Adds an external script.
void	addExternalScript(org.apache.hivemind.Resource resource) Adds an external script.
void	addInitializationScript(IComponent target, String script) Adds initialization script.
void	addInitializationScript(String script) Adds initialization script.
void	addScriptAfterInitialization(IComponent target, String script) Works in the same way as IScriptProcessor.addInitializationScript(IComponent, String) - except this method causes the script being added to appear after all of the script content written out from the normal initialization script processing happens.
void	addStatus(IMarkupWriter normalWriter, String text)
void	addStatusMessage(IMarkupWriter normalWriter, String category, String text) Adds a status message to the current response.
void	beginBodyScript(IMarkupWriter normalWriter, IRequestCycle cycle) Marks the beginning of the core body script.
boolean	contains(IComponent target) Determines if the specified component is contained in the responses requested update parts.
void	endBodyScript(IMarkupWriter normalWriter, IRequestCycle cycle) Marks the end of the body block being called.
boolean	explicitlyContains(IComponent target) Similar to ResponseBuilder.contains(IComponent), but only returns true if the component has been marked for update directly via an updateComponents property or by calling ResponseBuilder.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.
String	getPreloadedImageReference(IComponent target, IAsset source) Operates in the same way that PageRenderSupport.getPreloadedImageReference(IComponent, String) does, except the source is the actual IAsset of an image to preload.
String	getPreloadedImageReference(IComponent target, String url) Sets up the given URL to preload, and returns a reference to the loaded image, in the form of a snippet of JavaScript expression that can be inserted into some larger block of JavaScript as a function parameter, or as a property assignment.
String	getPreloadedImageReference(String url) Sets up the given URL to preload, and returns a reference to the loaded image, in the form of a snippet of JavaScript expression that can be inserted into some larger block of JavaScript as a function parameter, or as a property assignment.
String	getUniqueString(String baseValue) Ensures that the given string is unique.
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, IRequestCycle cycle) Invoked by components that know "when" the method should be called.
void	writeBodyScript(IMarkupWriter normalWriter, String script, IRequestCycle cycle) Called after ResponseBuilder.beginBodyScript(IMarkupWriter, IRequestCycle) to write the containing body script.
void	writeExternalScript(IMarkupWriter normalWriter, String url, IRequestCycle cycle) Invoked by PageRenderSupport to write external js package includes.
void	writeImageInitializations(IMarkupWriter normalWriter, String script, String preloadName, IRequestCycle cycle) Intended to be written within the confines of the body script, should be invoked once just after ResponseBuilder.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 normalWriter, String script) Writes any javascript that should only execute after all other items on a page have completed rendering.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DojoAjaxResponseBuilder

public DojoAjaxResponseBuilder(IRequestCycle cycle,
                               IMarkupWriter writer,
                               List parts,
                               List errorPages)

Creates a builder with a pre-configured IMarkupWriter. Currently only used for testing.

Parameters:

cycle - The current cycle.

writer - The markup writer to render all "good" content to.

parts - A set of string ids of the components that may have their responses rendered.

errorPages - List of page names known to be exception pages.

DojoAjaxResponseBuilder

public DojoAjaxResponseBuilder(IRequestCycle cycle,
                               IMarkupWriter writer,
                               List parts)

Creates a builder with a pre-configured IMarkupWriter. Currently only used for testing.

Parameters:

cycle - Current request.

writer - The markup writer to render all "good" content to.

parts - A set of string ids of the components that may have their responses rendered.

DojoAjaxResponseBuilder

public DojoAjaxResponseBuilder(IRequestCycle cycle,
                               RequestLocaleManager localeManager,
                               MarkupWriterSource markupWriterSource,
                               WebResponse webResponse,
                               List errorPages,
                               AssetFactory assetFactory,
                               String namespace,
                               IEngineService pageService)

Creates a new response builder with the required services it needs to render the response when renderResponse(IRequestCycle) is called.

Parameters:

cycle - The current request.

localeManager - Used to set the locale on the response.

markupWriterSource - Creates IJSONWriter instance to be used.

webResponse - Web response for output stream.

errorPages - List of page names known to be exception pages.

assetFactory - Used to manage asset source inclusions.

namespace - The core namespace to use for javascript/client side operations.

pageService - PageService used to generate page urls.

Method Detail

isDynamic

public boolean isDynamic()

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

Specified by:

isDynamic in interface ResponseBuilder

Returns:

Whether or not request is dynamic.

renderResponse

public void renderResponse(IRequestCycle cycle)
                    throws IOException

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

Specified by:

renderResponse in interface ResponseBuilder

Parameters:

cycle - The main request cycle object for this request.

Throws:

IOException - During io error.

flush

public void flush()
           throws IOException

Description copied from interface: ResponseBuilder

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.

Specified by:

flush in interface ResponseBuilder

Throws:

IOException - During io error.

updateComponent

public 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 ).

Specified by:

updateComponent in interface ResponseBuilder

Parameters:

id - The IComponent id to update.

getWriter

public 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)

Specified by:

getWriter in interface ResponseBuilder

Returns:

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

isBodyScriptAllowed

public boolean isBodyScriptAllowed(IComponent target)

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

Specified by:

isBodyScriptAllowed in interface IScriptProcessor

Parameters:

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

Returns:

True if the component script should be allowed.

isExternalScriptAllowed

public boolean isExternalScriptAllowed(IComponent target)

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

Specified by:

isExternalScriptAllowed in interface IScriptProcessor

Parameters:

target - The component to check for inclusion/exclusion.

Returns:

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

isInitializationScriptAllowed

public boolean isInitializationScriptAllowed(IComponent target)

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

Specified by:

isInitializationScriptAllowed in interface IScriptProcessor

Parameters:

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

Returns:

True if the component script should be allowed.

isImageInitializationAllowed

public boolean isImageInitializationAllowed(IComponent target)

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

Specified by:

isImageInitializationAllowed in interface ResponseBuilder

Parameters:

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

Returns:

True if the component script should be allowed.

getPreloadedImageReference

public String getPreloadedImageReference(IComponent target,
                                         IAsset source)

Operates in the same way that PageRenderSupport.getPreloadedImageReference(IComponent, String) does, except the source is the actual IAsset of an image to preload.

Specified by:

getPreloadedImageReference in interface PageRenderSupport

Parameters:

target - The component the asset is being loaded for.

source - The asset image to preload.

Returns:

The url representing the image that can be safely retrieved by the browser to see it.

getPreloadedImageReference

public String getPreloadedImageReference(IComponent target,
                                         String url)

Sets up the given URL to preload, and returns a reference to the loaded image, in the form of a snippet of JavaScript expression that can be inserted into some larger block of JavaScript as a function parameter, or as a property assignment. A typical return value might be tapestry_preload[7].src.

Specified by:

getPreloadedImageReference in interface PageRenderSupport

Parameters:

target - The component url being loaded for.

url - The asset URL to preload.

Returns:

Reference to preload image url.

getPreloadedImageReference

public String getPreloadedImageReference(String url)

Sets up the given URL to preload, and returns a reference to the loaded image, in the form of a snippet of JavaScript expression that can be inserted into some larger block of JavaScript as a function parameter, or as a property assignment. A typical return value might be tapestry_preload[7].src.

Specified by:

getPreloadedImageReference in interface PageRenderSupport

Parameters:

url - The url to the resource to be preloaded.

Returns:

Reference to preload image url.

addBodyScript

public void addBodyScript(IComponent target,
                          String script)

Adds scripting code to the main body. During the render, multiple scripts may render multiple bodies; all are concatinated together to form a single block. The Body component will write the body script contents just inside the <body> tag.

Specified by:

addBodyScript in interface IScriptProcessor

Parameters:

target - The component this script is being added for.

script - The script to add to the body response.

addBodyScript

public void addBodyScript(String script)

Adds scripting code to the main body. During the render, multiple scripts may render multiple bodies; all are concatinated together to form a single block. The Body component will write the body script contents just inside the <body> tag.

Specified by:

addBodyScript in interface IScriptProcessor

See Also:

#addBodyScript(IComponent, String)}

addExternalScript

public void addExternalScript(IComponent target,
                              org.apache.hivemind.Resource resource)

Adds an external script. The processor is expected to ensure that external scripts are only loaded a single time per page. The target will be checked to filter the scripts added for those types of responses that require them.

Specified by:

addExternalScript in interface IScriptProcessor

Parameters:

target - The component the script is being added for.

resource - The external script to add.

addExternalScript

public void addExternalScript(org.apache.hivemind.Resource resource)

Adds an external script. The processor is expected to ensure that external scripts are only loaded a single time per page.

Specified by:

addExternalScript in interface IScriptProcessor

See Also:

#addExternalScript(IComponent, Resource)}

addInitializationScript

public void addInitializationScript(IComponent target,
                                    String script)

Adds initialization script. Initialization script is executed once, when the containing page loads. Initialization script content is written only after all HTML content that could be referenced from the script (in effect, just before the </body> tag).

Specified by:

addInitializationScript in interface IScriptProcessor

Parameters:

target - The component the script is being added for.

script - The script to add.

addInitializationScript

public void addInitializationScript(String script)

Adds initialization script. Initialization script is executed once, when the containing page loads. Initialization script content is written only after all HTML content that could be referenced from the script (in effect, just before the </body> tag).

Specified by:

addInitializationScript in interface IScriptProcessor

See Also:

#addInitializationScript(IComponent, String)}

addScriptAfterInitialization

public void addScriptAfterInitialization(IComponent target,
                                         String script)

Description copied from interface: IScriptProcessor

Works in the same way as IScriptProcessor.addInitializationScript(IComponent, String) - except this method causes the script being added to appear after all of the script content written out from the normal initialization script processing happens. This is useful if you have some initialization script logic that absolutely must happen at the very end of the rest of things.

Specified by:

addScriptAfterInitialization in interface IScriptProcessor

Parameters:

target - The component the script is being added for.

script - The script to add.

See Also:

#addInitializationScript(IComponent, String)}.

getUniqueString

public String getUniqueString(String baseValue)

Ensures that the given string is unique. The string is either returned unchanged, or a suffix is appended to ensure uniqueness.

Specified by:

getUniqueString in interface IScriptProcessor

writeBodyScript

public 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.

Specified by:

writeBodyScript in interface ResponseBuilder

Parameters:

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

cycle - Associated request.

writeInitializationScript

public 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.

Specified by:

writeInitializationScript in interface ResponseBuilder

Parameters:

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

beginBodyScript

public void beginBodyScript(IMarkupWriter normalWriter,
                            IRequestCycle cycle)

Marks the beginning of the core body script.

Specified by:

beginBodyScript in interface ResponseBuilder

Parameters:

normalWriter - 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.

endBodyScript

public void endBodyScript(IMarkupWriter normalWriter,
                          IRequestCycle cycle)

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

Specified by:

endBodyScript in interface ResponseBuilder

Parameters:

normalWriter - 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.

writeBodyScript

public void writeBodyScript(IMarkupWriter normalWriter,
                            String script,
                            IRequestCycle cycle)

Called after ResponseBuilder.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.

Specified by:

writeBodyScript in interface ResponseBuilder

Parameters:

normalWriter - 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.

writeExternalScript

public void writeExternalScript(IMarkupWriter normalWriter,
                                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 .

Specified by:

writeExternalScript in interface ResponseBuilder

Parameters:

normalWriter - 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.

writeImageInitializations

public void writeImageInitializations(IMarkupWriter normalWriter,
                                      String script,
                                      String preloadName,
                                      IRequestCycle cycle)

Intended to be written within the confines of the body script, should be invoked once just after ResponseBuilder.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.

Specified by:

writeImageInitializations in interface ResponseBuilder

Parameters:

normalWriter - 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.

writeInitializationScript

public void writeInitializationScript(IMarkupWriter normalWriter,
                                      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.

Specified by:

writeInitializationScript in interface ResponseBuilder

Parameters:

normalWriter - 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.

addStatus

public void addStatus(IMarkupWriter normalWriter,
                      String text)

addStatusMessage

public void addStatusMessage(IMarkupWriter normalWriter,
                             String category,
                             String text)

Adds a status message to the current response. This implementation keeps track of all messages and appends them to the XHR response. On the client side, the default behavior is to publish the message to a topic matching the category name using dojo.event.topic.publish(category,text);.

Specified by:

addStatusMessage in interface ResponseBuilder

Parameters:

normalWriter - 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.

render

public 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.

Specified by:

render in interface ResponseBuilder

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

getWriter

public IMarkupWriter getWriter(String id,
                               String type)

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

Specified by:

getWriter in interface ResponseBuilder

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.

contains

public boolean contains(IComponent target)

Determines if the specified component is contained in the responses requested update parts.

Specified by:

contains in interface ResponseBuilder

Parameters:

target - The component to check for.

Returns:

True if the request should capture the components output.

explicitlyContains

public boolean explicitlyContains(IComponent target)

Similar to ResponseBuilder.contains(IComponent), but only returns true if the component has been marked for update directly via an updateComponents property or by calling ResponseBuilder.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 ResponseBuilder.contains(IComponent).

Specified by:

explicitlyContains in interface ResponseBuilder

Parameters:

target - The component to check.

Returns:

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