upd: Normalize tailing dots in "output.template"-Documentation

[gigi.git] / src / org / cacert / gigi / output / template / Form.java

diff --git a/src/org/cacert/gigi/output/template/Form.java b/src/org/cacert/gigi/output/template/Form.java
index f469c21c68bf53080d4f40863cb1e67a85dedc36..83a96f3813ad6bdb0c20bbc817f73f5eb2287b35 100644 (file)
--- a/src/org/cacert/gigi/output/template/Form.java
+++ b/src/org/cacert/gigi/output/template/Form.java
@@ -13,19 +13,53 @@ import org.cacert.gigi.localisation.Language;
 import org.cacert.gigi.pages.Page;
 import org.cacert.gigi.util.RandomToken;
 
+/**
+ * A generic HTML-form that handles CSRF-token creation.
+ */
 public abstract class Form implements Outputable {
 
     public static final String CSRF_FIELD = "csrf";
 
-    private String csrf;
+    private final String csrf;
 
+    private final String action;
+
+    /**
+     * Creates a new {@link Form}.
+     * 
+     * @param hsr
+     *            the request to register the form against.
+     */
     public Form(HttpServletRequest hsr) {
+        this(hsr, null);
+    }
+
+    /**
+     * Creates a new {@link Form}.
+     * 
+     * @param hsr
+     *            the request to register the form against.
+     * @param action
+     *            the target path where the form should be submitted.
+     */
+    public Form(HttpServletRequest hsr, String action) {
         csrf = RandomToken.generateToken(32);
+        this.action = action;
         HttpSession hs = hsr.getSession();
         hs.setAttribute("form/" + getClass().getName() + "/" + csrf, this);
-
     }
 
+    /**
+     * Update the forms internal state based on submitted data.
+     * 
+     * @param out
+     *            the stream to the user.
+     * @param req
+     *            the request to take the initial data from.
+     * @return true, iff the form succeeded and the user should be redirected.
+     * @throws GigiApiException
+     *             if internal operations went wrong.
+     */
     public abstract boolean submit(PrintWriter out, HttpServletRequest req) throws GigiApiException;
 
     protected String getCsrfFieldName() {
@@ -34,7 +68,11 @@ public abstract class Form implements Outputable {
 
     @Override
     public void output(PrintWriter out, Language l, Map<String, Object> vars) {
-        out.println("<form method='POST'>");
+        if (action == null) {
+            out.println("<form method='POST'>");
+        } else {
+            out.println("<form method='POST' action='" + action + "'>");
+        }
         failed = false;
         outputContent(out, l, vars);
         out.print("<input type='hidden' name='" + CSRF_FIELD + "' value='");
@@ -42,9 +80,19 @@ public abstract class Form implements Outputable {
         out.println("'></form>");
     }
 
+    /**
+     * Outputs the forms contents.
+     * 
+     * @param out
+     *            Stream to the user.
+     * @param l
+     *            {@link Language} to translate text to.
+     * @param vars
+     *            Variables supplied from the outside.
+     */
     protected abstract void outputContent(PrintWriter out, Language l, Map<String, Object> vars);
 
-    boolean failed;
+    private boolean failed;
 
     protected void outputError(PrintWriter out, ServletRequest req, String text, Object... contents) {
         if ( !failed) {
@@ -81,6 +129,17 @@ public abstract class Form implements Outputable {
         return csrf;
     }
 
+    /**
+     * Re-fetches a form e.g. when a Post-request is received.
+     * 
+     * @param req
+     *            the request that is directed to the form.
+     * @param target
+     *            the {@link Class} of the expected form.
+     * @return the form where this request is directed to.
+     * @throws CSRFException
+     *             if no CSRF-token is found or the token is wrong.
+     */
     public static <T extends Form> T getForm(HttpServletRequest req, Class<T> target) throws CSRFException {
         String csrf = req.getParameter(CSRF_FIELD);
         if (csrf == null) {
@@ -99,5 +158,7 @@ public abstract class Form implements Outputable {
 
     public static class CSRFException extends IOException {
 
+        private static final long serialVersionUID = 59708247477988362L;
+
     }
 }