1 package pl.caltha.forms;
2
3 import org.objectledge.parameters.Parameters;
4
5
6 /***
7 * Represents a form definition. Objects of this class are built upon an
8 * XML definition files.
9 * This objects is built from two functional elements:
10 * <ul>
11 * <li><strong>User Interface</strong> - also built upon XML definition file,
12 * which is referenced in form's definition (element
13 * <code><interface></code>, attribute <code>href</code>).</li>
14 * <li><strong>Form's Data Model</strong> - form's data model is created by
15 * three following parts:
16 * <ul>
17 * <li><strong>XML shemata</strong> which describes what type of data
18 * users input into the form - referenced in form's definition
19 * (element <code><model></code>,
20 * attribute <code>href</code>). Input data is kept as
21 * an XML document stored in {@link Instance} object.</li>
22 * <li><strong>Default Instance Document</strong> this is an XML document
23 * containing default input data for this form - it is also
24 * referenced in form's definition
25 * (element <code><instance></code>,
26 * attribute <code>href</code>).</li>
27 * <li><strong>Bind expressions</strong> which are defined by
28 * <code><bind></code> elements in form defintion file.</li>
29 * </ul>
30 * </li>
31 * </ul>
32 *
33 * @author <a href="mailto:zwierzem@ngo.pl">Damian Gajda</a>
34 * @version $Id: Form.java,v 1.3 2005/02/08 20:33:22 rafal Exp $
35 */
36 public interface Form
37 {
38 /*** Processes a user request merging it's data with an Instance object.
39 * <p>Processing consists of following steps:</p>
40 * <ol>
41 * <li><b>Value extraction (from the request) and are application on an Instance.</b>
42 * <p>This step is first because form-tool is a server-side tool.
43 * All values must be applied before Instance is validated, or
44 * any actions, including setting values dynamically are executed
45 * (If for instance setValue action would be executed before
46 * applying values, the result of this action could be lost).
47 * </p>
48 * <p>This action triggers bind property cache clean up
49 * ({@link pl.caltha.forms.internal.model.InstanceImpl})
50 * </p>
51 * </li>
52 * <li><b>Event extraction (from request) and dispatching.</b>
53 * <p>Event dispatching triggers actions connected to controls.
54 * These actions may also trigger another events and so on.</p>
55 * <p>TODO: Implement event - action loop protection.</p>
56 *
57 * <p>Right now only two kinds of events are extracted:</p>
58 * <ol>
59 * <li><code>activate</code> - control activation,
60 * in this case button control activation.</li>
61 * <li><code>submit</code> - submit button control activation.</li>
62 * </ol>
63 * </li>
64 * <li><b>Instance validation</b>
65 * <p>In client-side XForms implementation this step should be
66 * triggered by a changed value. In server-side processing value
67 * comparison would have to be implemented to check if any of them
68 * was changed. It is not very wise to do value comparison because
69 * there will be cases in which it will be faster to do validation
70 * than to compare all values in the Instance. That's why validation
71 * is always executed.
72 * </p>
73 * </li>
74 * </ol>
75 */
76 public void process(Instance instance, Parameters parameters)
77 throws Exception;
78
79 /*** Returns ID for this form's definition file. This is a form definition URI
80 * ({@link #getDefinitionURI}) changed to be compatible with XHTML IDs. */
81 public String getId();
82 /*** Returns URI for this form's definition file. */
83 public String getDefinitionURI();
84 /*** Returns URI for this form's User Interface definition file. */
85 public String getUIDefinitionURI();
86 /*** Returns URI for this form's XML schemata for Instances. */
87 public String getInstanceSchemaURI();
88 /*** Returns URI for this form's Default Instance document. */
89 public String getDefaultInstanceURI();
90 }