1 package pl.caltha.forms;
2
3 import java.util.Properties;
4
5 import org.objectledge.web.HttpContext;
6
7
8 /***
9 * FormTool service is used to generate and validate interactive HTML forms.
10 * As for now it is a partial <strong>Server-Side</strong> XForms implementation.
11 *
12 * @author <a href="mailto:zwierzem@ngo.pl">Damian Gajda</a>
13 * @version $Id: FormsService.java,v 1.4 2002/05/28 18:02:20 zwierzem Exp
14 * $
15 */
16 public interface FormsService
17 {
18 /*** The service name. */
19 public final static String SERVICE_NAME = "formtool";
20
21 /***
22 * XML namespace for ui definition scheme.<br />
23 * <code>http://www.cyklotron.net/2001/11/formtool-ui</code>.
24 */
25 public final static String ACCEPTED_NS_UI =
26 "http://www.cyklotron.net/2001/11/formtool-ui";
27 /***
28 * XML namespace for form definition scheme.<br />
29 * <code>http://www.cyklotron.net/2001/11/formtool-form</code>.
30 */
31 public final static String ACCEPTED_NS_FORM =
32 "http://www.cyklotron.net/2001/11/formtool-form";
33
34
35 /***
36 * Returns a Form definition object based on it's definition URI. Internally
37 * it builds this object and caches it for future use. This method also
38 * creates a name mapping for returned form definition object. It is
39 * allowed to map the same form under multiple names. When tere exists a
40 * different form (one with different deifinition URI) with the same name
41 * as one given in the parameters an exception is thrown.
42 *
43 * @param formDefinitionURI URI of a form definition file
44 * @param formName Name mapping for this form definition
45 * @return Form definition object
46 * @exception ConstructionException Thrown on errors when building the
47 * form definition object
48 * @exception FormsException Thrown on ambiguos formName =>
49 * form definition mapping
50 */
51 public Form getForm( String formDefinitionURI, String formName )
52 throws ConstructionException, FormsException;
53
54
55 /***
56 * Returns an {@link pl.caltha.forms.Instance} object depending
57 * on RunData parameters. If this object cannot be found it creates one
58 * depending on a given {@link pl.caltha.forms.Form} object.
59 *
60 * @param formName Form's system wide identifier, this one is
61 * used to allow same form definitions to be used in different site
62 * contexts.
63 * @param httpContext HttpConext for current request.
64 * @return found or newly created Instance object.
65 * @throws FormsException thrown when a found Instance is not an
66 * instance for a given Form definition.
67 */
68 public Instance getInstance( String formName,HttpContext httpContext )
69 throws FormsException;
70
71
72 /***
73 * Returns an Instance object creating it from a given saved state.
74 *
75 * @param formName Form's system wide identifier, this one is used to
76 * allow same form definitions to be used in different site contexts.
77 * @param httpContext HttpConext for current request.
78 * be stored in this user's session.
79 * @param savedState Serialized Instance data.
80 * @return Deserialized Instance object.
81 * @throws Exception thrown on problems with deserialization.
82 */
83 public Instance getInstance( String formName, HttpContext httpContext, byte[] savedState )
84 throws Exception;
85
86
87 /***
88 * Removes an instance from users session - it should be used after
89 * instance processing is finished. Otherwise heavy instance data will be
90 * kept during whole user session.
91 *
92 * @param httpContext HttpConext for current request.
93 * @param instance Description of Parameter
94 */
95 public void removeInstance(HttpContext httpContext, Instance instance);
96
97
98 public Properties getTidyConfiguration();
99 }
100