001: /* Initiator.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Thu Aug 4 12:09:19 2005, Created by tomyeh
010: }}IS_NOTE
011:
012: Copyright (C) 2005 Potix Corporation. All Rights Reserved.
013:
014: {{IS_RIGHT
015: This program is distributed under GPL Version 2.0 in the hope that
016: it will be useful, but WITHOUT ANY WARRANTY.
017: }}IS_RIGHT
018: */
019: package org.zkoss.zk.ui.util;
020:
021: import org.zkoss.zk.ui.Page;
022: import org.zkoss.zk.ui.UiException;
023:
024: /**
025: * Implemented by an initiator that will be invoked if it is specified
026: * in the init directive.
027: *
028: * <p><?init class="MyInit"?>
029: *
030: * <p>Once specified, an instance is created and {@link #doInit} is called
031: * before the page is evaluated. Then, {@link #doAfterCompose} is called
032: * after all components are created, and before any event is processed.
033: * In additions, {@link #doFinally} is called
034: * after the page has been evaluated. If an exception occurs, {@link #doCatch}
035: * is called.
036: *
037: * <p>A typical usage: starting a transaction in doInit, rolling back it
038: * in {@link #doCatch} and commit it in {@link #doFinally}
039: * (if {@link #doCatch} is not called).
040: *
041: * @author tomyeh
042: * @see InitiatorExt
043: */
044: public interface Initiator {
045: /** Does the initializes before the page is evaluated.
046: *
047: * <p>Note: when it is called, {@link Page#getDesktop},
048: * {@link Page#getId} and {@link Page#getTitle} all return null, since
049: * the page is not initialized yet.
050: * To get the current desktop, you have to use
051: * {@link org.zkoss.zk.ui.Execution#getDesktop} (from
052: * {@link org.zkoss.zk.ui.Executions#getCurrent}) instead.
053: * On the other hand, you can set the page's ID, title or style in
054: * this method (to override the declarations in the page definition)
055: * by {@link org.zkoss.zk.ui.Page#setId}, {@link Page#setTitle} and {@link Page#setStyle}.
056: * In additions, {@link Page#getRequestPath}
057: * and {@link Page#getAttribute} are all available.
058: *
059: * @param page the page being evaluated
060: * @param args an array of arguments passed with
061: * the arg0, arg1, arg2 and arg3 attributes (of the init directive).
062: * If no argument is specified, args is an array with zero length.
063: */
064: public void doInit(Page page, Object[] args) throws Exception;
065:
066: /** Called after all components are created (aka., composed),
067: * and before any event is processed.
068: *
069: * <p>Note: if {@link InitiatorExt} is also implemented,
070: * this method won't be called. Rather, {@link InitiatorExt#doAfterCompose}
071: * will be called instead.
072: *
073: * <p>For example, the data-binding managers could process the binding
074: * at this callback.
075: *
076: * <p>It won't be called if an un-caught exception occurs when creating
077: * components.
078: *
079: * @param page the page that new components are attached to. It is the same
080: * as {@link #doInit}'s page argument.
081: */
082: public void doAfterCompose(Page page) throws Exception;
083:
084: /** Called when an exception occurs during the evaluation of the page.
085: *
086: * <p>If you don't want to handle the exception, simply returns false.
087: * <code>boolean doCatch(Throwable ex) {return false;}</code>
088: *
089: * <p>An exception thrown in this method is simply logged. It has no
090: * effect on the execution.
091: * If you want to ignore the exception, just return true.
092: *
093: * <p>Notice: this method won't be called if the exception occurs
094: * in {@link #doInit}.
095: *
096: * @param ex the exception being thrown
097: * @return whether to ignore the exception. If false is returned,
098: * the exception will be re-thrown.
099: * Note: once an initiator's doCatch returns true, the exception will be
100: * ignored and it means doCatch of the following initiators won't be called.
101: * Prior to ZK 3.0.0, void is returned and it means always re-thrown
102: */
103: public boolean doCatch(Throwable ex) throws Exception;
104:
105: /** Do the cleanup after the page has been evaluated.
106: * It won't be called if {@link #doInit} throws an exception.
107: * However,it is always called no matter whether {@link #doCatch} is called.
108: *
109: * <p>An exception thrown in this method is simply logged. It has no
110: * effect on the execution.
111: */
112: public void doFinally() throws Exception;
113: }
|