01: /*
02: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
03: * Distributed under the terms of either:
04: * - the common development and distribution license (CDDL), v1.0; or
05: * - the GNU Lesser General Public License, v2.1 or later
06: * $Id: BeanHandler.java 3634 2007-01-08 21:42:24Z gbevin $
07: */
08: package com.uwyn.rife.template;
09:
10: import com.uwyn.rife.site.FormBuilder;
11: import com.uwyn.rife.template.exceptions.TemplateException;
12:
13: /**
14: * Handles the process of setting values in a template based on a Java bean
15: * instance.
16: *
17: * @author Keith Lea <keith[remove] at cs dot oswego dot edu>
18: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
19: * @version $Revision: 3634 $
20: * @since 1.0
21: */
22: public interface BeanHandler {
23: /**
24: * Sets all values in the given template whose names match names of
25: * properties in the given bean, preceded by the given prefix, if present.
26: * If the given prefix is <code>null</code>, it is ignored.
27: * <p>For example, given a class:
28: * <pre>class Person {
29: * private String first;
30: * private String last;
31: *
32: * public String getFirstName() { return first; }
33: * public void setFirstName(String name) { this.first = name; }
34: *
35: * public String getLastName() { return last; }
36: * public void setLastName(String name) { this.last = name; }
37: *}</pre>
38: * <p>And given a template:
39: * <pre>Hello <!--V 'NAME:firstName'/--> <!--V 'NAME:lastName'/-->.</pre>
40: * <p>Calling this method with an instance of Person where
41: * <code>first</code> was "<code>Jim</code>" and <code>last</code> was "<code>James</code>",
42: * and the prefix "<code>NAME:</code>", would produce:
43: * <pre>Hello Jim James.</pre>
44: * <p>Calling this method is equivalent to calling {@link
45: * Template#setValue(String, String) setValue} individually for each
46: * property of the bean prefixed with the given prefix.
47: * <p>If <code>encode</code> is <code>true</code>, this method will use
48: * the template's {@linkplain Template#getEncoder encoder} to encode the
49: * bean properties before setting the values.
50: * <p>Only <em>bean properties</em> will be considered for insertion in
51: * the template. This means only properties with a <em>getter and a setter</em>
52: * will be considered.
53: *
54: * @param template the template whose values will be filled
55: * @param bean a bean whose properties will be used to fill in values in
56: * the template
57: * @param prefix the prefix of values which will be filled with the given
58: * bean's property values
59: * @exception TemplateException if this template has no bean handling
60: * capability; or
61: * <p>an error occurred during the introspection of the bean
62: * @since 1.0
63: */
64: public void setBean(Template template, Object bean, String prefix,
65: boolean encode) throws TemplateException;
66:
67: /**
68: * Reverts all values to their defaults when the identifiers match
69: * properties of the given bean preceded by the given prefix, whether or
70: * not those values were set with a previous call to {@link
71: * Template#setBean(Object) }. The values of the bean's properties are
72: * ignored.
73: * <p>Calling this method is equivalent to calling {@link
74: * Template#removeValue } once for the name of each property of the given
75: * bean, prefixed with the given prefix.
76: *
77: * @param bean a bean whose property names will be used to determine
78: * whether
79: * @param prefix a prefix
80: * @exception TemplateException if this template has no bean handling
81: * capability; or
82: * <p>an error occurred during the introspection of the bean
83: * @since 1.0
84: */
85: public void removeBean(Template template, Object bean, String prefix)
86: throws TemplateException;
87:
88: /**
89: * Returns a form builder which will be used to {@linkplain
90: * com.uwyn.rife.engine.Element#generateForm(Template, Object) generate
91: * forms} in the corresponding template.
92: *
93: * @return a form builder for use with the corresponding template
94: * @since 1.0
95: */
96: public FormBuilder getFormBuilder();
97: }
|