org.hippoecm.hst.core.component

Interface HstResponse

All Superinterfaces:

javax.servlet.http.HttpServletResponse, javax.servlet.ServletResponse

public interface HstResponse
extends javax.servlet.http.HttpServletResponse

The HstResponse defines the interface to assist a HstComponent in creating and sending a response to the client. The HstComponent container uses specialized versions of this interface when invoking a HstComponent. The HstComponent container creates these objects and passes them as arguments to the HstComponent's doAction, doBeforeRender and doBeforeServeResource methods.

Version:

$Id$

Field Summary

Fields inherited from interface javax.servlet.http.HttpServletResponse

SC_ACCEPTED, SC_BAD_GATEWAY, SC_BAD_REQUEST, SC_CONFLICT, SC_CONTINUE, SC_CREATED, SC_EXPECTATION_FAILED, SC_FORBIDDEN, SC_FOUND, SC_GATEWAY_TIMEOUT, SC_GONE, SC_HTTP_VERSION_NOT_SUPPORTED, SC_INTERNAL_SERVER_ERROR, SC_LENGTH_REQUIRED, SC_METHOD_NOT_ALLOWED, SC_MOVED_PERMANENTLY, SC_MOVED_TEMPORARILY, SC_MULTIPLE_CHOICES, SC_NO_CONTENT, SC_NON_AUTHORITATIVE_INFORMATION, SC_NOT_ACCEPTABLE, SC_NOT_FOUND, SC_NOT_IMPLEMENTED, SC_NOT_MODIFIED, SC_OK, SC_PARTIAL_CONTENT, SC_PAYMENT_REQUIRED, SC_PRECONDITION_FAILED, SC_PROXY_AUTHENTICATION_REQUIRED, SC_REQUEST_ENTITY_TOO_LARGE, SC_REQUEST_TIMEOUT, SC_REQUEST_URI_TOO_LONG, SC_REQUESTED_RANGE_NOT_SATISFIABLE, SC_RESET_CONTENT, SC_SEE_OTHER, SC_SERVICE_UNAVAILABLE, SC_SWITCHING_PROTOCOLS, SC_TEMPORARY_REDIRECT, SC_UNAUTHORIZED, SC_UNSUPPORTED_MEDIA_TYPE, SC_USE_PROXY

Method Summary

Modifier and Type	Method and Description
void	addCookie(javax.servlet.http.Cookie cookie) Adds the specified cookie to the response.
void	addEpilogue(Comment comment) Add an epilogue comment, which gets rendered at the end of the render window.
void	addHeadElement(Element element, String keyHint) Adds an header element property to the response.
void	addPreamble(Comment comment) Add a preamble comment node, which gets rendered at the beginning of the render window.
void	addPreamble(Element element) Preamble Nodes are written before the rest of the content of this HstResponseState.
void	addProcessedHeadElement(Element headElement)
boolean	containsHeadElement(String keyHint) Asks if a property exists already or not.
HstURL	createActionURL() Creates a HST Action URL targeting the HstComponent.
Comment	createComment(String comment) Creates a comment element
HstURL	createComponentRenderingURL() Creates a HST component rendering URL targeting a specific HstComponent
Element	createElement(String tagName) Creates an element of the type specified to be used in the addPreamble(org.w3c.dom.Element) method.
HstURL	createNavigationalURL(String pathInfo) Creates a HST Navigational Render URL
HstURL	createRenderURL() Creates a HST Render URL targeting the HstComponent.
HstURL	createResourceURL() Creates a HST Resource URL targeting the current HstComponent.
HstURL	createResourceURL(String referenceNamespace) Creates a HST Resource URL targeting the HstComponent indicated by referenceNamespace.
void	flushChildContent(String name) Flushes the buffer of child window.
void	flushChildContent(String name, Writer writer) Flushes the child window, and writes its content to the Writer.
void	forward(String pathInfo) Forwards the page request to pathInfo.
List<String>	getChildContentNames() Returns the flushable child content window names.
List<Element>	getHeadElements() Retrieves header element list.
String	getNamespace() The value returned by this method should be prefixed or appended to elements, such as JavaScript variables or function names, to ensure they are unique in the context of the HST-managed page.
Element	getWrapperElement() Returns the wrapper element for the rendered content
boolean	isRendererSkipped() For single /subtree component rendering mode that has HstComponentInfo.isStandalone() equal to false, this check can be used whether some HstComponent won't get its renderer called.
void	sendError(int sc) Sends an error response to the client using the specified status.
void	sendError(int sc, String msg) Sends an error response to the client using the specified status.
void	sendRedirect(String location) Sends a temporary redirect response to the client using the specified redirect location URL.
void	setRenderParameter(String key, String value) Sets a String parameter for the rendering phase.
void	setRenderParameter(String key, String[] values) Sets a String parameter for the rendering phase.
void	setRenderParameters(Map<String,String[]> parameters) Sets a parameter map for the render request.
void	setRenderPath(String renderPath) Sets the renderPath dynamically.
void	setServeResourcePath(String serveResourcePath) Sets the serveResourcePath dynamically.
void	setStatus(int sc) Sets the status code for this response.
void	setWrapperElement(Element element) Sets wrapper element for the rendered content

Methods inherited from interface javax.servlet.http.HttpServletResponse

addDateHeader, addHeader, addIntHeader, containsHeader, encodeRedirectUrl, encodeRedirectURL, encodeUrl, encodeURL, getHeader, getHeaderNames, getHeaders, getStatus, setDateHeader, setHeader, setIntHeader, setStatus

Methods inherited from interface javax.servlet.ServletResponse

flushBuffer, getBufferSize, getCharacterEncoding, getContentType, getLocale, getOutputStream, getWriter, isCommitted, reset, resetBuffer, setBufferSize, setCharacterEncoding, setContentLength, setContentType, setLocale

Method Detail

createRenderURL

HstURL createRenderURL()

Creates a HST Render URL targeting the HstComponent.

createNavigationalURL

HstURL createNavigationalURL(String pathInfo)

Creates a HST Navigational Render URL

Parameters:

pathInfo - the path to be navigated

createActionURL

HstURL createActionURL()

Creates a HST Action URL targeting the HstComponent.

createResourceURL

HstURL createResourceURL()

Creates a HST Resource URL targeting the current HstComponent.

createResourceURL

HstURL createResourceURL(String referenceNamespace)

Creates a HST Resource URL targeting the HstComponent indicated by referenceNamespace.

Parameters:

referenceNamespace -

createComponentRenderingURL

HstURL createComponentRenderingURL()

Creates a HST component rendering URL targeting a specific HstComponent

Returns:

a component rendering ULR

getNamespace

String getNamespace()

The value returned by this method should be prefixed or appended to elements, such as JavaScript variables or function names, to ensure they are unique in the context of the HST-managed page. The namespace value must be constant for the lifetime of the HstComponentWindow.

setRenderParameter

void setRenderParameter(String key,
                        String value)

Sets a String parameter for the rendering phase. These parameters will be accessible in all sub-sequent render calls via the HstRequest.getParameter call until a request is targeted to the Hst component. This method replaces all parameters with the given key. The given parameter do not need to be encoded prior to calling this method.

Parameters:

key - key of the render parameter

value - value of the render parameter

setRenderParameter

void setRenderParameter(String key,
                        String[] values)

Sets a String parameter for the rendering phase. These parameters will be accessible in all sub-sequent render calls via the HstRequest.getParameter call until a request is targeted to the Hst component. This method replaces all parameters with the given key. The given parameter do not need to be encoded prior to calling this method.

Parameters:

key - key of the render parameter

values - values of the render parameters

setRenderParameters

void setRenderParameters(Map<String,String[]> parameters)

Sets a parameter map for the render request. All previously set render parameters are cleared. These parameters will be accessible in all sub-sequent renderinrg phase via the HstRequest.getParameter call until a new request is targeted to the Hst component. The given parameters do not need to be encoded prior to calling this method. The Hst component should not modify the map any further after calling this method.

Parameters:

parameters -

createElement

Element createElement(String tagName)

Creates an element of the type specified to be used in the addPreamble(org.w3c.dom.Element) method.

Parameters:

tagName - the tag name of the element

Returns:

DOM element with the tagName

createComment

Comment createComment(String comment)

Creates a comment element

Parameters:

comment - the comment text

Returns:

Comment DOM element with the text as content

addHeadElement

void addHeadElement(Element element,
                    String keyHint)

Adds an header element property to the response. If keyHint argument is provided and if a header element with the provided key hint already exists, then the element will be ignored. If the element is null the key is removed from the response. If these header values are intended to be transmitted to the client they should be set before the response is committed.

Parameters:

element -

keyHint -

getHeadElements

List<Element> getHeadElements()

Retrieves header element list. This method is supposed to be invoked by the parent HstComponent to render some header tag elements.

Returns:

List with head element items

containsHeadElement

boolean containsHeadElement(String keyHint)

Asks if a property exists already or not. This method checks all the parent component reponses have the property.

Parameters:

keyHint -

addProcessedHeadElement

void addProcessedHeadElement(Element headElement)

setRenderPath

void setRenderPath(String renderPath)

Sets the renderPath dynamically. Normally, the renderPath is set in the configuration, but it can be set dynamically in the HstComponent.doBeforeRender(HstRequest, HstResponse) method.

Parameters:

renderPath -

setServeResourcePath

void setServeResourcePath(String serveResourcePath)

Sets the serveResourcePath dynamically. Normally, the serveResourcePath is set in the configuration, but it can be set dynamically in the HstComponent.doBeforeServeResource(HstRequest, HstResponse) method.

Parameters:

serveResourcePath -

flushChildContent

void flushChildContent(String name)
                throws IOException

Flushes the buffer of child window.

Note: the child content can be flushed only once. If it is already flushed, then the next invocations will not make any effect.

Parameters:

name - the name of the child window

Throws:

IOException

flushChildContent

void flushChildContent(String name,
                       Writer writer)
                throws IOException

Flushes the child window, and writes its content to the Writer. Note that not everything that gets flushed ends up in the writer, for example head contributions not.

Parameters:

name - the name of the child window to flush

writer - the Writer the content gets flushed to

Throws:

IOException

getChildContentNames

List<String> getChildContentNames()

Returns the flushable child content window names.

sendRedirect

void sendRedirect(String location)
           throws IOException

Sends a temporary redirect response to the client using the specified redirect location URL.

In either HstComponent.doAction(HstRequest, HstResponse) or HstComponent.doBeforeRender(HstRequest, HstResponse) , the invocation on this method could be effective. If the invocation on this method is done in other methods, the invocation will be just ignored with no operation.

Specified by:

sendRedirect in interface javax.servlet.http.HttpServletResponse

Parameters:

location - the redirect location URL

Throws:

IOException

See Also:

HttpServletResponse.sendRedirect(String)

sendError

void sendError(int sc,
               String msg)
        throws IOException

Sends an error response to the client using the specified status.

Only in HstComponent.doAction(HstRequest, HstResponse), HstComponent.doBeforeRender(HstRequest, HstResponse) or HstComponent.doBeforeServeResource(HstRequest, HstResponse), the invocation on this method will be effective. If the invocation on this method is done in a view page during render phase, the invocation will be just ignored with no operation.

Specified by:

sendError in interface javax.servlet.http.HttpServletResponse

Parameters:

sc - the error status code

msg - the descriptive message

Throws:

IOException - If the response was committed

sendError

void sendError(int sc)
        throws IOException

Sends an error response to the client using the specified status.

Only in HstComponent.doAction(HstRequest, HstResponse), HstComponent.doBeforeRender(HstRequest, HstResponse) or HstComponent.doBeforeServeResource(HstRequest, HstResponse), the invocation on this method will be effective. If the invocation on this method is done in a view page during render phase, the invocation will be just ignored with no operation.

Specified by:

sendError in interface javax.servlet.http.HttpServletResponse

Parameters:

sc - the error status code

Throws:

IOException - If the response was committed

setStatus

void setStatus(int sc)

Sets the status code for this response. This method is used to set the return status code when there is no error (for example, for the status codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the caller wishes to invoke an error-page defined in the web application, the sendError method should be used instead.

If there are multiple HST components to invoke this method, then the last invocation will be applied.

Specified by:

setStatus in interface javax.servlet.http.HttpServletResponse

forward

void forward(String pathInfo)
      throws IOException

Forwards the page request to pathInfo.

Only in HstComponent.doBeforeRender(HstRequest, HstResponse), the invocation on this method will be effective. If the invocation on this method is done in a view page during render phase, the invocation will be just ignored with no operation.

Parameters:

pathInfo - the path info to forward. It should start with a "/" and is relative to the root of your hst sitemap

Throws:

IOException - If the response was committed

addCookie

void addCookie(javax.servlet.http.Cookie cookie)

Adds the specified cookie to the response. This method can be called multiple times to set more than one cookie.

Note: Please be sure to set cookie path before adding cookie for safety like the following example:

 Cookie cookie = new Cookie("testcookie", "testvalue");
 cookie.setPath("/");
 response.addCookie(cookie);
 

Sometimes, a user agent could not accept cookies when the response triggers page redirection with Set-Cookie header. It's possibly because it regards the state as an unverifiable transaction for some reason. By setting path, the cookie can be specified more as a subset of the current domain, and this makes sure that the cookie accepted safely by the user agent.

Specified by:

addCookie in interface javax.servlet.http.HttpServletResponse

Parameters:

cookie - the Cookie to return to the client

setWrapperElement

void setWrapperElement(Element element)

Sets wrapper element for the rendered content

Parameters:

element -

getWrapperElement

Element getWrapperElement()

Returns the wrapper element for the rendered content

addPreamble

void addPreamble(Comment comment)

Add a preamble comment node, which gets rendered at the beginning of the render window.

Parameters:

comment - the comment node

addPreamble

void addPreamble(Element element)

Preamble Nodes are written before the rest of the content of this HstResponseState. Note that from this element only the element, attributes and text of the element are printed, and *not* any descendant @link org.w3c.dom.Node}s of element

Parameters:

element - the element that is a preamble

addEpilogue

void addEpilogue(Comment comment)

Add an epilogue comment, which gets rendered at the end of the render window.

Parameters:

comment - the comment node

isRendererSkipped

boolean isRendererSkipped()

For single /subtree component rendering mode that has HstComponentInfo.isStandalone() equal to false, this check can be used whether some HstComponent won't get its renderer called. In other words, this is for performance optimization to short-circuit the doBeforeRender for components that won't get rendered any way.

Returns:

true when for this HstResponse the renderer won't be invoked