## res

    Object
       |
       +--res

SUMMARY: Constructor | Properties | Methods | DETAIL: Constructor | Properties | Methods

Properties Summary
`Boolean` | `cache` Specifies on a per-response base whether to allow client-side caching of the response or not.
`String` | `charset` Sets the character encoding of the output.
`String` | `contentType` Sets the content type of the HTTP response.
`Object` | `data` Object providing space for custom output data.
`String` | `error` Property containing an internal Helma error message.
`String` | `etag` Get or set the HTTP ETag for this response.
`Object` | `handlers` The res.handlers object is a container in the response object used to register macro handlers for the current request/response.
`Date` | `lastModified` Sets the date the resource was retrieved by the remote client.
`String` | `message` Buffers a string for output.
`Object` | `meta` Object providing space for general purpose per request meta information.
`String` | `realm` Sets the realm for a HTTP-authentication challenge This defines the realm for a HTTP-authentication challenge.
`HttpServletResponse` | `servletResponse` Provides direct access to the servlet response header, a Java object of the class Packages.javax.servlet.http.HttpServletResponse Example:
     res.servletResponse.setHeader( "Content-Disposition",
       ( this.mimetype.startsWith( "image/" )?
`Array` | `skinpath` The res.skinpath can be set to an array that tells Helma where to look for skinsets for the current request/response.
`Number` | `status` Read/write property containing the response's HTTP-status code.

Methods Summary
`void` | `abort()` Aborts the current transaction by throwing an Error
`void` | `commit()` Commits the current transaction, writing all changed objects to the database, and starts a new transaction.
`void` | `debug(<String> text)` Append any value to the output of the current page.
`void` | `dependsOn(<String> what)` Add an item to this response's dependencies.
`void` | `digest()` Digest this response's dependencies to conditionally create a HTTP not-modified response.
`void` | `encode(<String> textToEncode)` Writes a string as smooth HTML to the output buffer.
`void` | `encodeXml(<String> textToEncode)` Writes a string to the output buffer, replacing some characters with their equivalent XML entities.
`void` | `format(<String> textToFormat)` Writes a string as smooth HTML to the output buffer.
`void` | `forward(<String> path)` Serves a static file from the application's protectedStatic directory.
`String` | `getBuffer()` Provides access to the contents of the current repsonse buffer.
`String` | `pop()` Pops a string buffer from the response object and returns its string value.
`StringBuffer` | `popBuffer()` Pops the current response buffer without converting it to a string.
`void` | `push()` Pushes a new string buffer on the response object.
`void` | `pushBuffer(<StringBuffer> strBuffer)` Pushes a Java StringBuffer object on the reponse object.
`void` | `redirect()` Sends an HTTP redirect message to the client.
`void` | `reset()` Resets the current output buffer.
`void` | `setCookie(<String> key,<String> value,<Number> days,<String> path,<String> domain)` Sets a cookie to be sent to the client machine.
`void` | `stop()` Stops the execution of the request and sends the content of the reponse buffer.
`void` | `write(<String> text)` Writes a string to the output buffer.
`void` | `writeBinary(<Packages.java.ByteArray> data)` Writes binary data to the output buffer.
`void` | `writeln(<String> text)` Writes a string to the output buffer, adding a linebreak.

Properties Detail

### cache

    Boolean cache

Specifies on a per-response base whether to allow client-side caching of the response or not.
The default value is set to true but can be changed globally by passing caching = false to the initial Helma java call.
Please refer to the section about servlet properties for more details.
Example:

     res.cache = true

### charset

    String charset

Sets the character encoding of the output.
Sets Helma's character encoding according to the list of supported encodings. By default, Helma uses ISO-8859-1 (western) encoding. It is also possible to set the encoding server or application wide using the charset property in a properties file.
Be careful when setting the charset of a document containing a FORM. The browser returns the user-input encoded in the same way as the document. So if you set for instance the charest to UTF-8 (and don't set it in the app.properties or server.properties) you'll get scrambled input because Helma assumes the input is encoded in the standard encoding (default is ISO-8859-1). So you have to convert the returned strings from UTF8 to ISO-8859-1 (e.g. var string = new java.lang.String(new java.lang.String((req.data.input ? req.data.input : "")).getBytes("ISO-8859-1"), "UTF-8");).
Example:

     res.charset = "UTF8";
     res.write("Ä Ö Ü ä ö ü ß");
     // this is displayed if the brower's encoding is set to "Western"
     Ã „ Ã – Ã œ Ã ¤ Ã ¶ Ã ¼ Ã Ÿ

### contentType

    String contentType

Sets the content type of the HTTP response.
The default value is "text/html".
Example:

     res.contentType='text/plain';
     res.contentType='application/xhtml+xml';

### data

    Object data

Object providing space for custom output data.
This object can be used to attach any property propertyName onto it to make it available in a skin via the response macro.
Example:

     File root/main.skin:
     <html>
     <head>
     <title><% response.title %></title>
     </head>
     <body>
     <% response.body %>
     </body>
     </html>

     File root/main.hac:
     res.data.title = "Test";
     res.data.body = "Hello, World!";
     root.renderSkin("main");

     <html>
     <head>
     <title>Test</title>
     </head>
     <body>
     Hello, World!
     </body>
     </html>

### error

    String error

Property containing an internal Helma error message.
This property contains a string describing an error if one should have occured. If no error was detected, res.error contains null.
A good place for this function is a custom error page to display errors in a pretty layout.
Example:

     res.write(res.error);
     Runtime error Syntax error detected near line 1, column 24, after in string starting
     with: 'function main_action (arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10) {'...

### etag

    String etag

Get or set the HTTP ETag for this response.

### handlers

    Object handlers

The res.handlers object is a container in the response object used to register macro handlers for the current request/response.
Adding an object to res.handlers will make its macro functions and/or properties available as macros for skins.
By default, res.handlers contains the objects in the request path, registered by their prototype names. For instance, res.handlers.root will always be a reference to the app's root object.

### lastModified

    Date lastModified

Sets the date the resource was retrieved by the remote client.
By setting this property the remote client is told that the served resource has been modified at the given time. You then can check if the resource has changed given that the client includes this date in future requests for this resource.
Example:

     //in this example this.modificationDate is a property storing
     //the time of the last changes to the current object
     res.lastModified = this.modificationDate;

### message

    String message

Buffers a string for output.
When this property is set its value can be retrieved either by res.message from within an action or a JavaScript file or by the response macro from within a skin file.
Additionally, it will survive an HTTP redirect which can be necessary to display warnings or error messages to the user. The property's value will be reset to null not later than a redirected response was output.
Note: Please be aware that both res.message and res.data.message corresponds to the response.message macro. However, res.message has higher priority if both values should be set.
Example:

     File main.skin:
     <% response.message %>

     File main.hac:
     res.message = "Hello, World!";
     res.data.message = "Test";
     this.renderSkin("main");

     Hello, World!

### meta

    Object meta

Object providing space for general purpose per request meta information.
This object can be used to attach any property propertyName onto it to make it available within the scope a request.
Example:

     Inside an onRequest handler function:
       res.meta.permissions = this.doSomething();

     Inside an action such as delete.hac:
     if(res.meta.permissions | 7)
       this.remove();

### realm

    String realm

Sets the realm for a HTTP-authentication challenge
This defines the realm for a HTTP-authentication challenge. The realm is the name of a protected space. A server can have several realms, but resources within one realm should share the same authorisation - a valid authorisation should be valid as well for requesting another resource within the same realm.
Example:

     res.status = 401;
     res.realm = "Helma protected area";

### servletResponse

    HttpServletResponse servletResponse

Provides direct access to the servlet response header, a Java object of the class Packages.javax.servlet.http.HttpServletResponse
Example:

     res.servletResponse.setHeader( "Content-Disposition",
       ( this.mimetype.startsWith( "image/" )? "" : "attachment;" ) +
       "filename=\"" + this.name + "\"" );

### skinpath

    Array skinpath

The res.skinpath can be set to an array that tells Helma where to look for skinsets for the current request/response.
The elements of the array should be either HopObjects, which will be interpreted as database-resident skinsets, or strings, which will be interpreted as directory paths leading to file based skin sets.
If hobj is a HopObject element in the res.skinpath array, then a skin for prototype proto named sname is expected to reside in a string property in hobj.proto.sname.skin.
If path is a string, then the same skin will be looked up in a file called path/proto/sname.skin.

### status

    Number status

Read/write property containing the response's HTTP-status code.
This property defines the status code of the HTTP response. Like any HTTP-Server Helma can send the client software additional information describing the response. For a list of all codes and their meaning see RFC 2616. One of the common usages is to deny access and ask for authentication by responding with status code 401. The client software usually responds by asking the user for username and password. The default value is 200 which is the code for "OK".
Example:

     res.status = 401;
     //make sure to set res.realm as well when asking for http authentication
     res.realm = "Helma protected area";

Method Detail

### abort

    void abort()

Aborts the current transaction by throwing an Error

### commit

    void commit()

Commits the current transaction, writing all changed objects to the database, and starts a new transaction.
Usually, Helma automatically wraps each request into a database transaction. Use res.commit() if you have to modify a huge ammount of HopObjects within one request and want to partition the transaction into several smaller ones.
Example:

     for (var i in collection1)
       collection1.get(i).counter += 1;
     // commit changes to elements of collection1 to db
     res.commit();
     for (var i in collection2)
       collection2.get(i).counter -= 1;
     // changes to elements of collection2 are committed
     // automatically when the request terminates

### debug

    void debug(<String> text)

Append any value to the output of the current page.
All values written with res.debug() will appear as separate items at the bottom of the page. This assumes that the content type of the current request is text/html. Since items are simply appended to the full page, res.debug() will most likely break the well-fomedness of your page, but it is usually displayed properly.
Transforms the passed argument to a string (only if necessary) and appends the result to the response debug buffer.
Example:

     var now = new Date();
     res.debug("current time: " + now);

     current time: Tue May 20 18:59:02 CEST 2003

Parameters:

`text` - as String

### dependsOn

    void dependsOn(<String> what)

Add an item to this response's dependencies.
If no dependency has changed between requests, an HTTP not-modified response will be generated.

Parameters:

`what` - as string, an item this response depends on

### digest

    void digest()

Digest this response's dependencies to conditionally create a HTTP not-modified response.

### encode

    void encode(<String> textToEncode)

Writes a string as smooth HTML to the output buffer.
Encodes a string by replacing linebreaks with <br /> tags and diacritical characters as well as HTML tags with their equivalent HTML entities and immediately outputs it.
Example:

     res.encode("<b>Bananer växer\n minsann inte på träd.</b>");
     &lt;b&gt;Bananer v&auml;xer
     &lt;br /&gt; &lt;br&gt; minsann inte p&aring; tr&auml;d.&lt;/b&gt;

Parameters:

`textToEncode` - as String

See:

- encodeXml()

### encodeXml

    void encodeXml(<String> textToEncode)

Writes a string to the output buffer, replacing some characters with their equivalent XML entities.
This function substitutes the characters '<', '>', '&', as well as single and double quotes with their predefined XML 1.0 entities. Additionally, some characters that are illegal in XML documents are silently dropped.
encodeXml() is usually used to encode text for safe inclusion in parsed character data sections of XML documents.
Example:

     res.encodeXml("<title>Smørebr&oslash;d</title>");
     &lt;title&gt;Smørebr&amp;oslash;d&lt;/title&gt;

Parameters:

`textToEncode` - as String

See:

- encode()

### format

    void format(<String> textToFormat)

Writes a string as smooth HTML to the output buffer.
This function outputs a string after substituting special characters in a string with their equivalent HTML entities but keeping markup tags as is and also tries to avoid
tags where ever possible (e.g. in table structures).
Example:

     res.format("<table>\n<tr><td>Bananer växer\n minsann
     inte på träd.</td></tr>\n</table>");
     <table>
     <tr><td>Bananer v&auml;xer
     <br />
     minsann inte p&aring; tr&auml;d.</td></tr>
     </table>

Parameters:

`textToFormat` - as String

See:

- encode()

### forward

    void forward(<String> path)

Serves a static file from the application's protectedStatic directory.
Used to serve static files from the application's protectedStatic directory. This "protected" static directory needs to be set by defining an appname.protectedStatic property in the apps.properties file. The contents of that directory are not made directly accessible through the web, only through the use of this res.forward() method.

Parameters:

`path` - as String, relative to this app's protectedStatic directory

### getBuffer

    String getBuffer()

Provides access to the contents of the current repsonse buffer.
Useful for example when parsing/modifying the response after the request has been handled but before the response is returned.

Returns:

String

See:

- global.onResponse

### pop

    String pop()

Pops a string buffer from the response object and returns its string value.
This function "pops" a string buffer from the response object. The returned string contains all output written to the response since the last call of res.push().
Note that more than one string buffers can be pushed on the response object, and output always goes to the last one.
Example:

     res.push();
     res.write("foo");
     res.encode('.');
     res.write("bar");
     var str = res.pop()
     // str is "foo.bar"

Returns:

String

See:

- push()
- pushBuffer()
- popBuffer()

### popBuffer

    StringBuffer popBuffer()

Pops the current response buffer without converting it to a string.
This function "pops" the current StringBuffer from the response object and returns it as a Java StringBuffer object.

Returns:

StringBuffer

See:

- pop()
- pushBuffer()
- push()

### push

    void push()

Pushes a new string buffer on the response object.
This function "pushes" a fresh string buffer on the response object to which all response output will be redirected until res.pop() is called to retrieve the generated string.
Note that more than one string buffers can be pushed on the response object, and output always goes to the last one.
Example:

     res.push();
     res.write("foo");
     res.encode('.');
     res.write("bar");
     var str = res.pop();
     // str is "foo.bar"

See:

- pop()
- pushBuffer()
- popBuffer()

### pushBuffer

    void pushBuffer(<StringBuffer> strBuffer)

Pushes a Java StringBuffer object on the reponse object.
This function "pushes" the provided StringBuffer to the response object. All further writes will be redirected to this buffer.

Parameters:

`strBuffer` - as StringBuffer Java object, the StringBuffer to be pushed to the reponse object

See:

- pop()
- push()
- popBuffer()

### redirect

    void redirect()

Sends an HTTP redirect message to the client.
Note: JavaScript code following this command will be ignored.
Example:

     res.redirect(this.href());

### reset

    void reset()

Resets the current output buffer.
Example:

     res.write("Test");
     // changing my mind (e.g. an error occured)
     res.reset();
     res.write("Hello, World!");

     Hello, World!

### setCookie

    void setCookie(<String> key,<String> value,<Number> days,<String> path,<String> domain)

Sets a cookie to be sent to the client machine.
All arguments after nameString and valueString are optional.
daysNumber specifies the number of days until the cookie expires. If set to 0, the cookie will be deleted immediately. If the argument is not specified or set to a negative value, the cookie will be discarded is at the end of the browser session.
pathString specifies the path on which to set the cookie (defaults to /)
domainString specifies the domain on which to set the cookie (defaults to unset)
Example:

     res.setCookie("username", "michi");
     res.setCookie("password", "strenggeheim", 10, "/mypath", ".mydomain.org");

Parameters:

`key` - as String

`value` - as String

`days` - as Number

`path` - as String

`domain` - as String

### stop

    void stop()

Stops the execution of the request and sends the content of the reponse buffer.
Note that this method is intended for use in the context of an onRequest handler and not for use inside of actions, which would likely lead to bad coding practices.
Example:

    function onRequest() {
       if (fooIsCached()) {
         res.write(fooFromCache());
         res.stop();
       }
     }

### write

    void write(<String> text)

Writes a string to the output buffer.
Transforms the passed argument to a string (only if necessary) and appends the result to the response string buffer. Throws an error if no argument or an undefined argument is passed.
Example:

     var now = new Date();
     res.write("current time: " + now);

     current time: Thu Feb 15 23:34:29 GMT+01:00 2001

Parameters:

`text` - as String

### writeBinary

    void writeBinary(<Packages.java.ByteArray> data)

Writes binary data to the output buffer.
This function takes one argument, which must be a Java byte array. Useful when handling binary data retrieved via http file upload.
Example:

     var upload = req.data.fileUpload;
     res.writeBinary(upload.getContent());

Parameters:

`data` - as Packages.java.ByteArray

### writeln

    void writeln(<String> text)

Writes a string to the output buffer, adding a linebreak.
Transforms the passed argument to a string (only if necessary) and appends the result together with a trailing linebreak to the response string buffer. Throws an error if no argument or an undefined argument is passed.
Example:

     var now = new Date();
     res.writeln("current time:");
     res.writeln(now);

     current time:

     Thu Feb 15 23:34:29 GMT+01:00 2001

Parameters:

`text` - as String

SUMMARY: Constructor | Properties | Methods | DETAIL: Constructor | Properties | Methods

Documentation generated by JSDoc on Thu Apr 5 01:59:00 2007