001: package simpleorm.simplewebapp.core;
002:
003: /**
004: * Parent to WPagelet, mainly containing Event stubs.
005: * Overrides should always call super.<p>
006: *
007: * The events are generally grouped by pagelet, so that all of a pagelets
008: * processing happens at once.<p>
009: *
010: * But each pagelet's OnInitalize method is called first.
011: * Then each pagelets feilds are loaded but not validated.
012: * This is done before the non-interleaved events so that pagelets could interact with each other if really needed.<p>
013: *
014: * Then the for each pagelets their onPreValidate/Field Valdiation, *Submitted and Error events are called.
015: * These are not interleaved with other pagelets.<p>
016: *
017: * These non-interleaved methods can throw WValidationErrors will be caught and displayed to the user.
018: * This will prevent any further proccessing non-interleaved methods of this pagelet, but the page will continue.
019: * So a Crud error will not prevent a tree or list pagelet from working.<p>
020: *
021: * Then the onListRow methods are called as seen in the JSP.
022: * Finally each pagelet's onFinalize is called, after the JSP exits.<p>
023: *
024: * Normally a database connection is shared between pagelets, with error events doing rollbacks.
025: * Open the connection on the Page initializer, not the pagelet one.
026: * This approach keeps things simple.<p>
027: *
028: * (Why is this more complex than Rails (say)? Mainly because we support the
029: * implementation of independently written pagelets.)<p>
030: *
031: * (See WPageStructure.main() for precice details as to how these are called.) <p>
032: *
033: * (Having the *Submitted events is a little more compex than just having one
034: * doBody event and testing if wasSubmitted within it. But it is convenient to have
035: * these split up for the user.
036: * Individual buttons are not split up because typically one wants shared processing
037: * between Insert, Update, Delete user actions.)<p>
038: *
039: * (To extend a Page/Pagelet one simply subtypes them, and thus having access to
040: * the super types events.
041: * However, might allow other non-pagelet classes to extend this directly later,
042: * and then regester themselves to receive the events. But not now.)<p>
043: *
044: */
045: abstract class WPageEvents {
046:
047: /**
048: * Override this to initalize the system, as an alternative to constructors.
049: * Called for each pagelet up front, before field values are retrieved,
050: * so can be used to generate fields. <p>
051: *
052: * wPageContext has been set before this is called.
053: * WValidationErrors are NOT caught here and will kill the page. <p>
054: *
055: * Not a good place to open db connections, particularly thread local ones,
056: * as other paglets' onInitialize will be called before the body of this pagelet
057: * is executed.
058: * onPreValidate or onPreMaybeSubmitted are better places to open connections
059: * if that needs to be done on a per pagelet level.<p>
060: */
061: protected void onInitialize() throws Exception {
062: }
063:
064: /**
065: * Override this to close database connections etc.
066: * Guaranteed to always be called, even if there are errors,
067: * normally by </WPage>.<p>
068: */
069: protected void onFinalize() throws Exception {
070: }
071:
072: /** Provided to destroy data structures in case onFinalize does not call Super. */
073: void onFinalizeInternal() throws Exception {
074: }
075:
076: /**
077: * Called after field.text values have been retrieved but before validators have been run.
078: * Thus data values will not be set up yet.
079: * Any thrown WValidationErrors will be caught and displayed to the user,
080: * and will prevent further validation or processing of the PageLET.
081: * Often used to define buttons.
082: * Not interleaved with other pagelets, see class docs.
083: */
084: protected void onPreValidate() throws Exception {
085: }
086:
087: /**
088: * Override this to process the form data just before either onNotSubmitted or onWasSubmitted,
089: * but after all the field validators have succeeded.
090: * Ie. Called regardless of whether the form was called from a menu or posted back.
091: * Can be used to open datbase connections etc.
092: * Can throw WValidationErrors will be caught and displayed to the user.
093: * Not interleaved with other pagelets, see class docs.
094: */
095: protected void onPreMaybeSubmitted() throws Exception {
096: }
097:
098: /**
099: * Called when the form is called initially from a menu, ie not submitted via a submit button.
100: * All fields are set and validated.
101: * Can throw WValidationErrors will be caught and displayed to the user.
102: * Not interleaved with other pagelets, see class docs.
103: */
104: protected void onNotSubmitted() throws Exception {
105: }
106:
107: /**
108: * Called when the form is submitted via a submit button, normally back to itself.
109: * Ie. not from a menu.
110: * All fields are set and validated.
111: * Can throw WValidationErrors will be caught and displayed to the user.
112: * Not interleaved with other pagelets, see class docs.
113: */
114: protected void onWasSubmitted() throws Exception {
115: }
116:
117: /**
118: * Override this to process the form data just after either onNotSubmitted or onWasSubmitted.
119: * Ie. Called regardless of whether the form was called from a menu or posted back.
120: * Can throw WValidationErrors will be caught and displayed to the user.
121: * Not interleaved with other pagelets, see class docs.
122: */
123: protected void onPostMaybeSubmitted() throws Exception {
124: }
125:
126: /**
127: * Called just after onPostMaybeSubmitted, but called even if an earlier
128: * method produces a WValidation error.
129: * Use isErroneous to determine whether the pageLET had thrown an validation exception.<p>
130: *
131: * Use this to rollback Crud pages if necessary. We don't do this by default
132: * because there may be Tree or List pagelets following, which need to run.
133: * (Non-WValidationExceptions always just abort the entire page -- they are a programming error.)<p>
134: *
135: * Can also throw WValidationErrors will be caught and displayed to the user.
136: * Not interleaved with other pagelets, see class docs.<p>
137: */
138: protected void onMaybeErroneous() throws Exception {
139: }
140:
141: /** For list pagelets, this is called once for each iteration of the
142: * JSP's foreachrow loop. Return false when there is no more data to
143: * display.<p>
144: *
145: * Normally the implementation moves data into the WField objects in the
146: * list group.
147: * The JSP then just accesses the field values directly, as
148: * ${WPage.fields.myfield}.<p>
149: *
150: * This is a low level interface that can be used to set any field attributes,
151: * once per field. Eg. AnchorHRefs, but also anything else eg. highlight some rows.
152: * A high level DataSet oriented structure might be added later.<p>
153: *
154: * Calls to this are suppressed if WPagelet.isErroneous() because
155: * queries that drive it are unlikely to be set up.<p>
156: *
157: * Obviously not interleaved with other pagelets, see class docs.
158: *
159: * @see WFieldGroupList which maps the foreach collection to this method.
160: */
161: protected boolean onListRow() throws Exception {
162: throw new RuntimeException("onListRow Not implemented ");
163: }
164:
165: }
|