* Implement unsetCookie(name) that causes a prevously set cookie to be discarded

* Add Javadoc comments to all methods

src/helma/framework/ResponseBean.java

@@ -32,63 +32,64 @@ public class ResponseBean implements Serializable {
     /**
      * Creates a new ResponseBean object.
      *
-     * @param res ...
+     * @param res the wrapped ResponseTrans
      */
     public ResponseBean(ResponseTrans res) {
         this.res = res;
     }
 
     /**
+     * Write an object to the response buffer by converting it to a string
+     * and then HTML-encoding it.
      *
-     *
+     * @param obj the object to write to the response buffer 
-     * @param what ...
      */
-    public void encode(Object what) {
+    public void encode(Object obj) {
-        res.encode(what);
+        res.encode(obj);
     }
 
     /**
+     * Write an object to the response buffer by converting it to a string
+     * and then XML-encoding it.
      *
-     *
+     * @param obj the object to write to the response buffer 
-     * @param what ...
      */
-    public void encodeXml(Object what) {
+    public void encodeXml(Object obj) {
-        res.encodeXml(what);
+        res.encodeXml(obj);
     }
 
     /**
+     * Write an object to the response buffer by converting it to a string
+     * and then HTML-formatting it.
      *
-     *
+     * @param obj the object to write to the response buffer 
-     * @param what ...
      */
-    public void format(Object what) {
+    public void format(Object obj) {
-        res.format(what);
+        res.format(obj);
     }
 
     /**
+     * Redirect the request to a different URL
      *
-     *
+     * @param url the URL to redirect to
-     * @param url ...
+     * @throws RedirectException to immediately terminate the request
-     *
-     * @throws RedirectException ...
      */
     public void redirect(String url) throws RedirectException {
         res.redirect(url);
     }
 
     /**
+     * Internally forward the request to a different URL
      *
-     *
+     * @param url the URL to forward to
-     * @param url ...
+     * @throws RedirectException to immediately terminate the request
-     *
-     * @throws RedirectException ...
      */
     public void forward(String url) throws RedirectException {
         res.forward(url);
     }
 
     /**
-     *
+     * Reset the response object, clearing all content previously written to it
      */
     public void reset() {
         res.reset();
@@ -103,258 +104,283 @@ public class ResponseBean implements Serializable {
     }
 
     /**
+     * Set a HTTP cookie with the name and value that is discarded when the 
+     * HTTP client is closed
      *
-     *
+     * @param key the cookie name
-     * @param key ...
+     * @param value the cookie value
-     * @param value ...
      */
     public void setCookie(String key, String value) {
         res.setCookie(key, value, -1, null, null);
     }
 
     /**
+     * Set a HTTP cookie with the name and value that is stored by the 
+     * HTTP client for the given number of days. A days value of 0 means the
+     * cookie should be immediately discarded.
      *
-     *
+     * @param key the cookie name
-     * @param key ...
+     * @param value the cookie value
-     * @param value ...
+     * @param days number of days the cookie should be stored
-     * @param days ...
      */
     public void setCookie(String key, String value, int days) {
         res.setCookie(key, value, days, null, null);
     }
 
     /**
+     * Set a HTTP cookie with the name and value that is only applied to 
+     * the URLs matching the given path and is stored by the 
+     * HTTP client for the given number of days. A days value of 0 means the
+     * cookie should be immediately discarded.
      *
-     *
+     * @param key the cookie name
-     * @param key ...
+     * @param value the cookie value
-     * @param value ...
+     * @param days number of days the cookie should be stored
-     * @param days ...
+     * @param path the URL path to apply the cookie to
-     * @param path ...
      */
     public void setCookie(String key, String value, int days, String path) {
         res.setCookie(key, value, days, path, null);
     }
 
     /**
+     * Set a HTTP cookie with the name and value that is only applied to 
+     * the URLs matching the given path and is stored by the 
+     * HTTP client for the given number of days. A days value of 0 means the
+     * cookie should be immediately discarded.
      *
-     *
+     * @param key the cookie name
-     * @param key ...
+     * @param value the cookie value
-     * @param value ...
+     * @param days number of days the cookie should be stored
-     * @param days ...
+     * @param path the URL path to apply the cookie to
-     * @param path ...
+     * @param domain domain
-     * @param domain ...
      */
     public void setCookie(String key, String value, int days, String path, String domain) {
         res.setCookie(key, value, days, path, domain);
     }
     
     /**
+     * Unset a previously set HTTP cookie, causing it to be discarded immedialtely by the 
+     * HTTP client.
      *
-     *
+     * @param key the name of the cookie to be discarded
-     * @param what ...
      */
-    public void write(String what) {
+    public void unsetCookie(String key) {
-        res.write(what);
+        res.setCookie(key, "", 0, null, null);
     }
 
     /**
+     * Directly write a string to the response buffer without any transformation.
      *
-     *
+     * @param str the string to write to the response buffer
-     * @param what ...
      */
-    public void writeln(String what) {
+    public void write(String str) {
-        res.writeln(what);
+        res.write(str);
     }
 
     /**
+     * Write a string to the response buffer followed by an XHTML br tag.
      *
-     *
+     * @param str the string to write to the response buffer
-     * @param what ...
      */
-    public void writeBinary(byte[] what) {
+    public void writeln(String str) {
-        res.writeBinary(what);
+        res.writeln(str);
     }
 
     /**
+     * Directly write a byte array to the response buffer without any transformation.
      *
+     * @param bytes the string to write to the response buffer
+     */
+    public void writeBinary(byte[] bytes) {
+        res.writeBinary(bytes);
+    }
+
+    /**
+     * add an HTML formatted debug message to the end of the page.
      *
-     * @param message ...
+     * @param message the message
      */
     public void debug(String message) {
         res.debug(message);
     }
 
     /**
+     * Return a string representation for this object
      *
-     *
+     * @return string representation
-     * @return ...
      */
     public String toString() {
         return "[Response]";
     }
 
-    // property-related methods:
+    // property-related methods
+    
+    /**
+     * Return the current cachability setting for this response
+     * 
+     * @return true if the response may be cached by the HTTP client, false otherwise
+     */
     public boolean getCache() {
         return res.cache;
     }
 
     /**
+     * Set true cachability setting for this response
      *
-     *
+     * @param cache true if the response may be cached by the HTTP client, false otherwise
-     * @param cache ...
      */
     public void setCache(boolean cache) {
         res.cache = cache;
     }
 
     /**
+     * Get the current charset/encoding name for the response
      *
-     *
+     * @return The charset name
-     * @return ...
      */
     public String getCharset() {
         return res.charset;
     }
 
     /**
+     * Set the charset/encoding name for the response
      *
-     *
+     * @param charset The charset name
-     * @param charset ...
      */
     public void setCharset(String charset) {
         res.charset = charset;
     }
 
     /**
+     * Get the current content type name for the response
      *
-     *
+     * @return the content type
-     * @return ...
      */
     public String getContentType() {
         return res.contentType;
     }
 
     /**
+     * Set the content type for the response
      *
-     *
+     * @param contentType The charset name
-     * @param contentType ...
      */
     public void setContentType(String contentType) {
         res.contentType = contentType;
     }
 
     /**
+     * Get the data map for the response
      *
-     *
+     * @return the data object
-     * @return ...
      */
     public Map getData() {
         return res.getResponseData();
     }
 
     /**
+     * Get the macro handlers map for the response
      *
-     *
+     * @return the macro handlers map
-     * @return ...
      */
     public Map getHandlers() {
         return res.getMacroHandlers();
     }
     
     /**
+     * Get the meta map for the response
      *
-     *
+     * @return the meta map
-     * @return ...
      */
     public Map getMeta() {
         return res.getMetaData();
     }
 
     /**
+     * Get the current error message for the response, if any
      *
-     *
+     * @return the error message
-     * @return ...
      */
     public String getError() {
         return res.error;
     }
 
     /**
+     * Get the current message for the response, if set
      *
-     *
+     * @return the message
-     * @return ...
      */
     public String getMessage() {
         return res.message;
     }
 
     /**
+     * Set the message property for the response
      *
-     *
+     * @param message the message property
-     * @param message ...
      */
     public void setMessage(String message) {
         res.message = message;
     }
 
     /**
+     * Get the HTTP authentication realm for the response
      *
-     *
+     * @return the HTTP authentication realm
-     * @return ...
      */
     public String getRealm() {
         return res.realm;
     }
 
     /**
+     * Set the HTTP authentication realm for the response
      *
-     *
+     * @param realm the HTTP authentication realm
-     * @param realm ...
      */
     public void setRealm(String realm) {
         res.realm = realm;
     }
 
     /**
+     * Set the skin search path for the response
      *
-     *
+     * @param arr an array containing files or nodes containing skins
-     * @param arr ...
      */
     public void setSkinpath(Object[] arr) {
         res.setSkinpath(arr);
     }
 
     /**
+     * Get the skin search path for the response
      *
-     *
+     * @return The array of files or nodes used to search for skins
-     * @return ...
      */
     public Object[] getSkinpath() {
         return res.getSkinpath();
     }
 
     /**
+     * Get the HTTP status code for this response
      *
-     *
+     * @return the HTTP status code
-     * @return ...
      */
     public int getStatus() {
         return res.status;
     }
 
     /**
+     * Set the HTTP status code for this response
      *
-     *
+     * @param status the HTTP status code
-     * @param status ...
      */
     public void setStatus(int status) {
         res.status = status;
     }
 
     /**
+     * Get the last modified date for this response
      *
-     *
+     * @return the last modified date
-     * @return ...
      */
     public Date getLastModified() {
         long modified = res.getLastModified();
@@ -367,9 +393,9 @@ public class ResponseBean implements Serializable {
     }
 
     /**
+     * Set the last modified date for this response
      *
-     *
+     * @param date the last modified date
-     * @param date ...
      */
     public void setLastModified(Date date) {
         if (date == null) {
@@ -380,34 +406,35 @@ public class ResponseBean implements Serializable {
     }
 
     /**
+     * Get the ETag for this response
      *
-     *
+     * @return the HTTP etag
-     * @return ...
      */
     public String getETag() {
         return res.getETag();
     }
 
     /**
+     * Set the HTTP Etag for this response
      *
-     *
+     * @param etag the HTTP ETag
-     * @param etag ...
      */
     public void setETag(String etag) {
         res.setETag(etag);
     }
 
     /**
+     * Add an item to this response's dependencies. If no dependency has changed between 
+     * requests, an HTTP not-modified response will be generated.
      *
-     *
+     * @param what a string item this response depends on
-     * @param what ...
      */
     public void dependsOn(String what) {
         res.dependsOn(what);
     }
 
     /**
-     *
+     * Digest this response's dependencies to conditionally create a HTTP not-modified response
      */
     public void digest() {
         res.digestDependencies();