Package helma.framework

# Class ResponseTrans

java.lang.Object
java.io.Writer
helma.framework.ResponseTrans

All Implemented Interfaces:
  `Closeable`, `Flushable`, `Serializable`, `Appendable`, `AutoCloseable`

public final class ResponseTrans extends Writer implements Serializable
A Transmitter for a response to the servlet client. Objects of this class are directly exposed to JavaScript as global property res.

See Also:
  - Serialized Form

## Field Summary

### Fields inherited from class java.io.Writer

`lock`

## Constructor Summary

Constructors
Constructor
Description
`ResponseTrans(Application app, RequestTrans req)`
Creates a new ResponseTrans object.

## Method Summary

Modifier and Type
Method
Description
`void`
`addDateHeader(String name, Date value)`
Proxy to HttpServletResponse.addDateHeader()
`void`
`addHeader(String name, String value)`
Proxy to HttpServletResponse.addHeader()
`void`
`cacheSkin(Object id, Skin skin)`
Cache a skin for the length of this response.
`void`
`close()`
This has to be called after writing to this response has finished and before it is shipped back to the web server.
`void`
`close(String defaultCharset)`
This has to be called after writing to this response has finished and before it is shipped back to the web server.
`int`
`countCookies()`
Get the number of cookies set in this response.
`void`
`debug(Object message)`
Insert string somewhere in the response buffer.
`void`
`dependsOn(Object what)`
Add a dependency to this response.
`void`
`digestDependencies()`
Digest all dependencies to a checksum to see if the response has changed.
`void`
`encode(Object what)`
Replace special characters with entities, including `<`, `>` and `"`, thus allowing no HTML tags.
`void`
`encodeForm(Object what)`
Encode HTML entities, but leave newlines alone.
`void`
`encodeXml(Object what)`
Replace special characters with entities, including `<`, `>` and `"`, thus allowing no HTML tags.
`void`
`flush()`
`void`
`format(Object what)`
Replace special characters with entities but pass through HTML tags
`void`
`forward(String url)`
`Object`
`get(String name)`
Get a value from the responses map by key.
`Skin`
`getActiveSkin()`
Return the skin currently being rendered, or none.
`StringBuffer`
`getBuffer()`
Get the response buffer, creating it if it doesn't exist
`Skin`
`getCachedSkin(Object id)`
Look up a cached skin.
`String`
`getCharset()`
Get the charset/encoding for this response
`byte[]`
`getContent()`
Get the body content for this response as byte array, encoded using the response's charset.
`int`
`getContentLength()`
Get the number of bytes of the response body.
`String`
`getContentType()`
Get the response's MIME content type
`CookieTrans[]`
`getCookies()`
Get the cookies set in this response.
`StringBuffer`
`getDebugBuffer()`
Get debug messages to append to the response, if any.
`Throwable`
`getError()`
Get the error message to display to the user, if any.
`String`
`getErrorMessage()`
`String`
`getETag()`
Get the ETag header value for this response.
`String`
`getForward()`
`long`
`getLastModified()`
Get the value of the Last-Modified header for this response.
`Map`
`getMacroHandlers()`
Get the macro handlers map for this response transmitter.
`String`
`getMessage()`
Get the message to display to the user, if any.
`Map`
`getMetaData()`
Get the meta info map for this response transmitter.
`boolean`
`getNotModified()`
Check if this response should generate a Not-Modified response.
`String`
`getRealm()`
Get the HTTP authentication realm
`String`
`getRedirect()`
`Map`
`getResponseData()`
Get the data map for this response transmitter.
`javax.servlet.http.HttpServletResponse`
`getServletResponse()`
Returns the ServletResponse instance for this ResponseTrans.
`Object[]`
`getSkinpath()`
Get the path in which to look for skins.
`int`
`getStatus()`
Get the HTTP response status code
`boolean`
`isCacheable()`
Returns true if this response may be cached by the client
`StringBuffer`
`popBuffer()`
`String`
`popString()`
Returns the content of the current string buffer and switches back to the previos one.
`StringBuffer`
`pushBuffer(StringBuffer buf)`
This is called before a skin is rendered as string (renderSkinAsString) to redirect the output to a new string buffer.
`void`
`redirect(String url)`
`void`
`reportError(String errorMessage)`
Write a vanilla error report.
`void`
`reportError(Throwable throwable)`
Write a vanilla error report.
`void`
`reset()`
Reset the response object to its initial empty state.
`void`
`resetBuffer()`
Reset the current response buffer.
`void`
`resetCookies()`
Reset all previously set cookies.
`void`
`setCacheable(boolean cache)`
Set the cacheability of this response
`void`
`setCharset(String charset)`
Set the charset/encoding for this response
`void`
`setContentType(String contentType)`
Set the response's MIME content type
`void`
`setCookie(String key, String value, int days, String path, String domain, boolean isHttpOnly, boolean isSecure)`
Set a cookie.
`void`
`setDateHeader(String name, Date value)`
Proxy to HttpServletResponse.setDateHeader()
`void`
`setDebugBuffer(StringBuffer debugBuffer)`
Set debug messages to append to the response.
`void`
`setError(Throwable error)`
Set a message to display to the user.
`void`
`setETag(String value)`
Set the ETag header value for this response.
`void`
`setHeader(String name, String value)`
Proxy to HttpServletResponse.setHeader()
`void`
`setLastModified(long modified)`
Set the Last-Modified header for this response
`void`
`setMessage(String message)`
Set a message to display to the user.
`void`
`setRealm(String realm)`
Set the HTTP authentication realm
`void`
`setSkinpath(Object[] arr)`
Set the path in which to look for skins.
`void`
`setStatus(int status)`
Set the HTTP response status code
`Skin`
`switchActiveSkin(Skin skin)`
Set the skin currently being rendered, returning the previously active skin.
`void`
`waitForClose()`
If we just attached to evaluation we call this instead of close because only the primary thread is responsible for closing the result
`void`
`write(char[] chars)`
Appends a char array to the response buffer.
`void`
`write(char[] chars, int offset, int length)`
Appends a part from a char array to the response buffer.
`void`
`write(int c)`
Appends a signle character to the response buffer.
`void`
`write(Object what)`
Appends a objct to the response unchanged.
`void`
`write(String str)`
Append a string to the response unchanged.
`void`
`write(String str, int offset, int length)`
Appends a part from a string to the response buffer.
`void`
`writeBinary(byte[] bytes)`
Allow to directly set the byte array for the response.
`void`
`writeln()`
Writes a platform dependent newline sequence to response buffer.
`void`
`writeln(Object what)`
Write object to response buffer and append a platform dependent newline sequence.
`void`
`writeXmlRpcError(Exception x)`
`void`
`writeXmlRpcResponse(Object result)`

### Methods inherited from class java.io.Writer

`append, append, append, nullWriter`

### Methods inherited from class java.lang.Object

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

## Constructor Details

### ResponseTrans

public ResponseTrans(Application app, RequestTrans req)
Creates a new ResponseTrans object.

Parameters:
  `req` - the RequestTrans for this response

## Method Details

### get

public Object get(String name)
Get a value from the responses map by key.

### getResponseData

public Map getResponseData()
Get the data map for this response transmitter.

### getMacroHandlers

public Map getMacroHandlers()
Get the macro handlers map for this response transmitter.

### getMetaData

public Map getMetaData()
Get the meta info map for this response transmitter.

### getServletResponse

public javax.servlet.http.HttpServletResponse getServletResponse()
Returns the ServletResponse instance for this ResponseTrans. Returns null for internal and XML-RPC requests.

### resetBuffer

public void resetBuffer()
Reset the current response buffer.

### reset

public void reset()
Reset the response object to its initial empty state.

### pushBuffer

public StringBuffer pushBuffer(StringBuffer buf)
This is called before a skin is rendered as string (renderSkinAsString) to redirect the output to a new string buffer.

Parameters:
  `buf` - the StringBuffer to use, or null
Returns:
  the new StringBuffer instance

### popString

public String popString()
Returns the content of the current string buffer and switches back to the previos one.

### popBuffer

public StringBuffer popBuffer()

### getBuffer

public StringBuffer getBuffer()
Get the response buffer, creating it if it doesn't exist

### write

public void write(String str)
Append a string to the response unchanged.

Overrides:
  `write` in class `Writer`

### write

public void write(Object what)
Appends a objct to the response unchanged. The object is first converted to a string.

### write

public void write(char[] chars, int offset, int length)
Appends a part from a char array to the response buffer.

Specified by:
  `write` in class `Writer`
Parameters:
  `chars` -
  `offset` -
  `length` -

### write

public void write(char[] chars)
Appends a char array to the response buffer.

Overrides:
  `write` in class `Writer`
Parameters:
  `chars` -

### write

public void write(int c)
Appends a signle character to the response buffer.

Overrides:
  `write` in class `Writer`
Parameters:
  `c` -

### write

public void write(String str, int offset, int length)
Appends a part from a string to the response buffer.

Overrides:
  `write` in class `Writer`
Parameters:
  `str` -
  `offset` -
  `length` -

### writeln

public void writeln(Object what)
Write object to response buffer and append a platform dependent newline sequence.

### writeln

public void writeln()
Writes a platform dependent newline sequence to response buffer.

### debug

public void debug(Object message)
Insert string somewhere in the response buffer. Caller has to make sure that buffer exists and its length is larger than offset. str may be null, in which case nothing happens.

### encode

public void encode(Object what)
Replace special characters with entities, including `<`, `>` and `"`, thus allowing no HTML tags.

### format

public void format(Object what)
Replace special characters with entities but pass through HTML tags

### encodeXml

public void encodeXml(Object what)
Replace special characters with entities, including `<`, `>` and `"`, thus allowing no HTML tags.

### encodeForm

public void encodeForm(Object what)
Encode HTML entities, but leave newlines alone. This is for the content of textarea forms.

### redirect

public void redirect(String url) throws RedirectException

Parameters:
  `url` - ...
Throws:
  `RedirectException` - ...

### getRedirect

public String getRedirect()

Returns:
  ...

### forward

public void forward(String url) throws RedirectException

Parameters:
  `url` - ...
Throws:
  `RedirectException` - ...

### getForward

public String getForward()

Returns:
  ...

### writeBinary

public void writeBinary(byte[] bytes)
Allow to directly set the byte array for the response. Calling this more than once will overwrite the previous output.

Parameters:
  `bytes` - an arbitrary byte array

### addHeader

public void addHeader(String name, String value)
Proxy to HttpServletResponse.addHeader()

Parameters:
  `name` - the header name
  `value` - the header value

### addDateHeader

public void addDateHeader(String name, Date value)
Proxy to HttpServletResponse.addDateHeader()

Parameters:
  `name` - the header name
  `value` - the header value

### setHeader

public void setHeader(String name, String value)
Proxy to HttpServletResponse.setHeader()

Parameters:
  `name` - the header name
  `value` - the header value

### setDateHeader

public void setDateHeader(String name, Date value)
Proxy to HttpServletResponse.setDateHeader()

Parameters:
  `name` - the header name
  `value` - the header value

### reportError

public void reportError(Throwable throwable)
Write a vanilla error report. Callers should make sure the ResponeTrans is new or has been reset.

Parameters:
  `throwable` - the error

### reportError

public void reportError(String errorMessage)
Write a vanilla error report. Callers should make sure the ResponeTrans is new or has been reset.

Parameters:
  `errorMessage` - the error message

### writeXmlRpcResponse

public void writeXmlRpcResponse(Object result)

### writeXmlRpcError

public void writeXmlRpcError(Exception x)

### flush

public void flush()

Specified by:
  `flush` in interface `Flushable`
Specified by:
  `flush` in class `Writer`

### close

public void close() throws UnsupportedEncodingException
This has to be called after writing to this response has finished and before it is shipped back to the web server. Transforms the string buffer into a byte array for transmission.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in class `Writer`
Throws:
  `UnsupportedEncodingException`

### close

public void close(String defaultCharset) throws UnsupportedEncodingException
This has to be called after writing to this response has finished and before it is shipped back to the web server. Transforms the string buffer into a byte array for transmission.

Parameters:
  `defaultCharset` - the charset to use if no explicit charset has been set on the response
Throws:
  `UnsupportedEncodingException` - if the charset is not a valid encoding name

### waitForClose

public void waitForClose()
If we just attached to evaluation we call this instead of close because only the primary thread is responsible for closing the result

### getContent

public byte[] getContent()
Get the body content for this response as byte array, encoded using the response's charset.

Returns:
  the response body

### getContentLength

public int getContentLength()
Get the number of bytes of the response body.

Returns:
  the length of the response body

### getContentType

public String getContentType()
Get the response's MIME content type

Returns:
  the MIME type for this response

### setContentType

public void setContentType(String contentType)
Set the response's MIME content type

Parameters:
  `contentType` - MIME type for this response

### setLastModified

public void setLastModified(long modified)
Set the Last-Modified header for this response

Parameters:
  `modified` - the Last-Modified header in milliseconds

### getLastModified

public long getLastModified()
Get the value of the Last-Modified header for this response.

Returns:
  the Last-Modified header in milliseconds

### setETag

public void setETag(String value)
Set the ETag header value for this response.

Parameters:
  `value` - the ETag header value

### getETag

public String getETag()
Get the ETag header value for this response.

Returns:
  the ETag header value

### getNotModified

public boolean getNotModified()
Check if this response should generate a Not-Modified response.

Returns:
  true if the the response wasn't modified since the client last saw it.

### dependsOn

public void dependsOn(Object what)
Add a dependency to this response.

Parameters:
  `what` - an item this response's output depends on.

### digestDependencies

public void digestDependencies()
Digest all dependencies to a checksum to see if the response has changed.

### setSkinpath

public void setSkinpath(Object[] arr)
Set the path in which to look for skins. This may contain file locations and HopObjects.

Parameters:
  `arr` - the skin path

### getSkinpath

public Object[] getSkinpath()
Get the path in which to look for skins. This may contain file locations and HopObjects.

Returns:
  the skin path

### getCachedSkin

public Skin getCachedSkin(Object id)
Look up a cached skin.

Parameters:
  `id` - the skin key
Returns:
  the skin, or null if no skin is cached for the given key

### cacheSkin

public void cacheSkin(Object id, Skin skin)
Cache a skin for the length of this response.

Parameters:
  `id` - the skin key
  `skin` - the skin to cache

### switchActiveSkin

public Skin switchActiveSkin(Skin skin)
Set the skin currently being rendered, returning the previously active skin.

Parameters:
  `skin` - the new active skin
Returns:
  the previously active skin

### getActiveSkin

public Skin getActiveSkin()
Return the skin currently being rendered, or none.

Returns:
  the currently active skin

### setCookie

public void setCookie(String key, String value, int days, String path, String domain, boolean isHttpOnly, boolean isSecure)
Set a cookie.

Parameters:
  `key` - the cookie key
  `value` - the cookie value
  `days` - the cookie's lifespan in days
  `path` - the URL path to apply the cookie to
  `domain` - the domain to apply the cookie to
  `isHttpOnly` - marks the cookie as HttpOnly
  `isSecure` - limits the cookie for use with secure protocols

### resetCookies

public void resetCookies()
Reset all previously set cookies.

### countCookies

public int countCookies()
Get the number of cookies set in this response.

Returns:
  the number of cookies

### getCookies

public CookieTrans[] getCookies()
Get the cookies set in this response.

Returns:
  the cookies

### getMessage

public String getMessage()
Get the message to display to the user, if any.

Returns:
  the message

### setMessage

public void setMessage(String message)
Set a message to display to the user.

Parameters:
  `message` - the message

### getError

public Throwable getError()
Get the error message to display to the user, if any.

Returns:
  the error message

### setError

public void setError(Throwable error)
Set a message to display to the user.

Parameters:
  `error` - the error message

### getErrorMessage

public String getErrorMessage()

### getDebugBuffer

public StringBuffer getDebugBuffer()
Get debug messages to append to the response, if any.

Returns:
  the response's debug buffer

### setDebugBuffer

public void setDebugBuffer(StringBuffer debugBuffer)
Set debug messages to append to the response.

Parameters:
  `debugBuffer` - the response's debug buffer

### getCharset

public String getCharset()
Get the charset/encoding for this response

Returns:
  the charset name

### setCharset

public void setCharset(String charset)
Set the charset/encoding for this response

Parameters:
  `charset` - the charset name

### isCacheable

public boolean isCacheable()
Returns true if this response may be cached by the client

Returns:
  true if the response may be cached

### setCacheable

public void setCacheable(boolean cache)
Set the cacheability of this response

Parameters:
  `cache` - true if the response may be cached

### getStatus

public int getStatus()
Get the HTTP response status code

Returns:
  the HTTP response code

### setStatus

public void setStatus(int status)
Set the HTTP response status code

Parameters:
  `status` - the HTTP response code

### getRealm

public String getRealm()
Get the HTTP authentication realm

Returns:
  the name of the authentication realm

### setRealm

public void setRealm(String realm)
Set the HTTP authentication realm

Parameters:
  `realm` - the name of the authentication realm