001: /*
002: * Created on Aug 9, 2005
003: */
004: package uk.org.ponder.rsf.components;
005:
006: /**
007: * This is essentially the core RSF component.
008: *
009: * Represents a single (possibly vector) value as transferred between the bean
010: * model and the rendererd view. Unless this is a pure output component, the
011: * value will be bound to an (EL) bean reference. This reference is used both on
012: * render to give them their initial values, and on submission to apply the
013: * input value to the model. <br>
014: * Immediate descendents are UIInput(One) and UIInputMany, as well as UIOutput.
015: * <br>
016: * A bound value may well be the container for other bound values, or
017: * annotations of other types. However, any containment hierarchy below this
018: * level is invisible to IKAT, which hands off component subtrees to renderers
019: * at anything below UIBranchContainer.
020: * <p>
021: * The most important and commonly set fields of UIBound are <code>value</code>
022: * and <code>valuebinding</code>. The fields <code>willinput</code> and
023: * <code>fossilize</code> are generally set by subclasses such as UIInput and
024: * UIOutput used to define the nature of the component. The fields
025: * <code>darshaper</code> and <code>resolver</code> are set in more advanced
026: * scenarios where some type adjustment is required. Finally the fields
027: * <code>fossilizedbinding</code> and <code>fossilizedshaper</code> should
028: * not be set by client code - they are a convenient repository for rendered
029: * bindings as they pass through the fixup stage.
030: *
031: * @author Antranig Basman (antranig@caret.cam.ac.uk)
032: */
033: public abstract class UIBound extends UIComponent {
034: /**
035: * The EL value reference that this component's value is bound to. This will
036: * be a string of the form <code>#{rootbean.property1.property2}</code>
037: */
038: public ELReference valuebinding;
039: /**
040: * An EL reference to a "DAR reshaper" that should be used to adjust the value
041: * of any attempt to write a value based on the valuebinding. The reference
042: * should be to a bean of type {@link uk.org.ponder.mapping.DARReshaper}.
043: * <p>
044: * This is principally (currently) useful for selection controls, where a
045: * write of the value (typically an Object ID) that was read via the
046: * valuebinding would not have the "correct" effect on the object model. This
047: * field will typically be <code>null</code>.
048: */
049: public ELReference darreshaper;
050: /**
051: * The "initial" or "current" value of the component. Since components in
052: * general only exist between production and rendering, this value is a
053: * transit between these processes and is not subject to any amusing
054: * processing. In general, this value <it>may</it> be set an initial value by
055: * the producer. If it is not set a value, <it>and</it> the
056: * <code>valuebinding</code> is set, the value will be queried from the bean
057: * model during the fixup phase.
058: * <p>
059: * I would dearly have loved to have made this value of differing concrete
060: * types in subclasses (<code>boolean</code>, <code>String[]</code> &c)
061: * but this created too much of a burden for fixup code. Also, fixups need to
062: * be able to reliably distinguish a missing value <code>null</code> which
063: * would be impossible with a primitive type.
064: * <p>
065: * Most importantly, <code>value</code> itself must never become
066: * independently visible as an bean property to serializers, which should
067: * instead only see the typesafe access functions defined in subclasses. For
068: * this reason, the field itself is protected, and the accessors are called
069: * <code>acquireValue</code> and <code>updateValue</code>
070: */
071: protected Object value;
072:
073: /**
074: * Returns the "value" Object reference. This method and
075: * <code>updateValue</code> are not named "get" and "set" to avoid confusing
076: * bean serialisers.
077: */
078: public Object acquireValue() {
079: return value;
080: }
081:
082: /** Sets the "value" Object reference */
083: public void updateValue(Object value) {
084: this .value = value;
085: }
086:
087: /** A reference to an object, or an object that can be converted to, a
088: * LeafRenderer or BeanResolver that can render the bound value above
089: * to and from a String representation, or applied to elements of the array
090: * if a String array.
091: */
092: public Object resolver;
093:
094: /**
095: * A field recording whether the value of this binding at render time will be
096: * "fossilized", i.e. recorded by the client and resubmitted with modified
097: * values. Defaults to <code>true</code> for input components, and
098: * <code>false</code> for output components.
099: * <p>
100: * Producers of output components with high consistency requirements (i.e.
101: * those that will be used to provide critical values to users during multi-
102: * requests should override the constructor default in UIOutput with
103: * <code>true</code>.
104: */
105: public boolean fossilize = false;
106: /**
107: * A field recording whether any input is expected to result from this
108: * component. Note that if this flag is set to <code>true</code>, the
109: * <code>fossilize</code> flag MUST also be set to true.
110: */
111: public boolean willinput = false;
112:
113: /** A field recording whether "unchanged value detection" will apply to this
114: * component's submission. If this flag is set to <code>true</code>, submitted
115: * values will *always* be applied to the model irrespective of any
116: * environment settings.
117: */
118: public boolean mustapply = false;
119: /**
120: * The key/value pair that will be submitted to implement the fossilized
121: * binding. Component producers should NOT attempt to set this field, it will
122: * be computed during a fixup.
123: */
124: public UIParameter fossilizedbinding;
125: /**
126: * The key/value pair of the binding corresponding to the DAR reshaper. Again,
127: * computed during fixup stage if the darshaper is set.
128: */
129: public UIParameter fossilizedshaper;
130:
131: /** The key that this bound control will submit under. May be set during
132: * early fixup - if not, will default to the fullID of the component, unless
133: * the renderer has special requirements (e.g. radio button group).
134: */
135: public String submittingname;
136: }
|