org.zkoss.zk.ui.util
Interface Initiator

All Known Implementing Classes:
AnnotateDataBinderInit, Composition, ZScriptInitiator

public interface Initiator

Implemented by an initiator that will be invoked if it is specified in the init directive.

<?init class="MyInit"?>

Once specified, an instance is created and doInit(org.zkoss.zk.ui.Page, java.util.Map) is called before the page is evaluated. Then, doAfterCompose(org.zkoss.zk.ui.Page) is called after all components are created, and before any event is processed. In additions, doFinally() is called after the page has been evaluated. If an exception occurs, doCatch(java.lang.Throwable) is called.

A typical usage: starting a transaction in doInit, rolling back it in doCatch(java.lang.Throwable) and commit it in doFinally() (if doCatch(java.lang.Throwable) is not called).

Author:
tomyeh
See Also:
InitiatorExt

Method Summary
 void doAfterCompose(Page page)
          Called after all components are created (aka., composed), and before any event is processed.
 boolean doCatch(java.lang.Throwable ex)
          Called when an exception occurs during the evaluation of the page.
 void doFinally()
          Do the cleanup after the page has been evaluated.
 void doInit(Page page, java.util.Map args)
          Does the initializes before the page is evaluated.
 

Method Detail

doInit

void doInit(Page page,
            java.util.Map args)
            throws java.lang.Exception
Does the initializes before the page is evaluated.

Note: when it is called, Page.getDesktop(), Page.getId() and Page.getTitle() all return null, since the page is not initialized yet. To get the current desktop, you have to use Execution.getDesktop() (from Executions.getCurrent()) instead. On the other hand, you can set the page's ID, title or style in this method (to override the declarations in the page definition) by Page.setId(java.lang.String), Page.setTitle(java.lang.String) and Page.setStyle(java.lang.String). In additions, Page.getRequestPath() and Page.getAttribute(java.lang.String, int) are all available.

Parameters:
page - the page being evaluated
args - a map of arguments. Prior to 3.6.2, it is an array. To upgrade, use args.get("arg0") instead of args[0], args.get("arg1") instead of args[1] and so on. Of course, it is better to have a more meaningful name for each argument. If no argument is specified, args is an empty map (never null).
Throws:
java.lang.Exception

doAfterCompose

void doAfterCompose(Page page)
                    throws java.lang.Exception
Called after all components are created (aka., composed), and before any event is processed.

Note: if InitiatorExt is also implemented, this method won't be called. Rather, InitiatorExt.doAfterCompose(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Component[]) will be called instead.

For example, the data-binding managers could process the binding at this callback.

It won't be called if an un-caught exception occurs when creating components.

Parameters:
page - the page that new components are attached to. It is the same as doInit(org.zkoss.zk.ui.Page, java.util.Map)'s page argument.
Throws:
java.lang.Exception

doCatch

boolean doCatch(java.lang.Throwable ex)
                throws java.lang.Exception
Called when an exception occurs during the evaluation of the page.

If you don't want to handle the exception, simply returns false. boolean doCatch(Throwable ex) {return false;}

An exception thrown in this method is simply logged. It has no effect on the execution. If you want to ignore the exception, just return true.

Notice: this method won't be called if the exception occurs in doInit(org.zkoss.zk.ui.Page, java.util.Map).

Parameters:
ex - the exception being thrown
Returns:
whether to ignore the exception. If false is returned, the exception will be re-thrown. Note: once an initiator's doCatch returns true, the exception will be ignored and it means doCatch of the following initiators won't be called. Prior to ZK 3.0.0, void is returned and it means always re-thrown
Throws:
java.lang.Exception

doFinally

void doFinally()
               throws java.lang.Exception
Do the cleanup after the page has been evaluated. It won't be called if doInit(org.zkoss.zk.ui.Page, java.util.Map) throws an exception. However,it is always called no matter whether doCatch(java.lang.Throwable) is called.

An exception thrown in this method is simply logged. It has no effect on the execution.

Throws:
java.lang.Exception


Copyright © 2005-2009 Potix Corporation. All Rights Reserved. SourceForge.net Logo