Package org.zkoss.zk.ui.util

## Class GenericAutowireComposer<T extends Component>

- java.lang.Object
- - org.zkoss.zk.ui.event.GenericEventListener
  - - org.zkoss.zk.ui.util.GenericComposer<T>
    - - org.zkoss.zk.ui.util.GenericAutowireComposer<T>

- All Implemented Interfaces:
    `java.io.Serializable`, `EventListener`, `SerializableEventListener`, `ComponentActivationListener`, `ComponentCloneListener`, `Composer<T>`, `ComposerExt<T>`
  Direct Known Subclasses:
    `GenericForwardComposer`

      public abstract class GenericAutowireComposer<T extends Component>
      extends GenericComposer<T>
      implements ComponentCloneListener, ComponentActivationListener

  A skeletal composer that you can extend and write intuitive onXxx event handler methods with "auto-wired" accessible variable objects such as implicit objects, components, and external resolvable variables in a ZK zuml page. This class will registers onXxx events to the supervised component and wire all accessible variable objects to this composer by calling setXxx() method or set xxx field value directly per the variable name. Since 3.0.7, this composer has wired all implicit objects such as self, spaceOwner, page, desktop, session, application, componentScope, spaceScope, pageScope, desktopScope, sessionScope, applicationScope, and requestScope, so you can use them directly. Besides that, it also provides alert(String message) method, so you can call alert() without problems. Since 3.5.2, the composer itself would be assigned as an attribute of the supervised component per the naming convention of the component id and composer class name or of component id and "composer". e.g. If the component id is "mywin" and the composer class is org.zkoss.MyComposer, then the composer can be referenced by the variable name of "mywin$MyController" or "mywin$composer". Notice that the '$' separator can be changed to other character such as '_' for Groovy or other environment that '$' is not applicable. Simply extends this class and calling `GenericAutowireComposer(char separator)` constructor with proper separator character.

  Alternatives: in most cases, you don't extend from `GenericAutowireComposer` directly. Rather, you can extend from one of the following skeletons.

  `SelectorComposer`
    It supports the autowiring based on Java annotation and a CSS3-based selector. If you don't know which one to use, use `SelectorComposer`.
  `GenericForwardComposer`
    It supports the autowiring based on naming convention. You don't need to specify annotations explicitly, but it is error-prone if it is used properly.

  Notice that since this composer kept references to the components, single instance composer object cannot be shared by multiple components.

  The following is an example. The onOK event listener is registered into the target window, and the Textbox component with id name "mytextbox" is injected into the "mytextbox" field automatically (so you can use mytextbox variable directly in onOK). The "value" property of "mytextbox" is assigned with composer's getTitle(), i.e. "ZK".

       MyComposer.java

       public class MyComposer extends GenericAutowireComposer {
           private Textbox mytextbox;

           public void onOK() {
               mytextbox.setValue("Enter Pressed");
               alert("Hi!");
           }
           public String getTitle() {
               return "ZK";
           }
       }

       test.zul

       <window id="mywin" apply="MyComposer">
           <textbox id="mytextbox" value="${mywin$composer.title}"/>
       </window>

  Since 5.0.8, you could name the composer by specify a custom attribute called `composerName`. For example,

       <window apply="MyComposer">
       <custom-attribute composerName="mc"/>
           <textbox id="mytextbox" value="${mc.title}"/>
       </window>

  Since:
    3.0.6
  Author:
    henrichen
  See Also:
    `ConventionWires`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected char` | `_separator` | The separator used to separate the component ID and event name.
    `protected WebApp` | `application` | Implicit Object; the web application.
    `protected java.util.Map<java.lang.String,​java.lang.Object>` | `applicationScope` | Implicit Object; a map of attributes defined in the web application.
    `protected java.util.Map<?,​?>` | `arg` | Implicit Object; the arg argument passed to the createComponents method.
    `protected java.util.Map<java.lang.String,​java.lang.Object>` | `componentScope` | Implicit Object; a map of attributes defined in the applied component.
    `protected Desktop` | `desktop` | Implicit Object; the desktop.
    `protected java.util.Map<java.lang.String,​java.lang.Object>` | `desktopScope` | Implicit Object; a map of attributes defined in the desktop.
    `protected Execution` | `execution` | Implicit Object; the current execution.
    `protected Page` | `page` | Implicit Object; the page.
    `protected java.util.Map<java.lang.String,​java.lang.Object>` | `pageScope` | Implicit Object; a map of attributes defined in the page.
    `protected java.util.Map<java.lang.String,​java.lang.String[]>` | `param` | Implicit Object; the param argument passed from the http request.
    `protected java.util.Map<java.lang.String,​java.lang.Object>` | `requestScope` | Implicit Object; a map of attributes defined in the request.
    `protected T` | `self` | Implicit Object; the applied component itself.
    `protected Session` | `session` | Implicit Object; the session.
    `protected java.util.Map<java.lang.String,​java.lang.Object>` | `sessionScope` | Implicit Object; a map of attributes defined in the session.
    `protected IdSpace` | `spaceOwner` | Implicit Object; the space owner of the applied component.
    `protected java.util.Map<java.lang.String,​java.lang.Object>` | `spaceScope` | Implicit Object; a map of attributes defined in the ID space contains the applied component.

    - ### Fields inherited from class org.zkoss.zk.ui.util.GenericComposer

      `_applied`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `GenericAutowireComposer()` | The default constructor.
    `protected` | `GenericAutowireComposer​(char separator)` | Constructor with a custom separator.
    `protected` | `GenericAutowireComposer​(char separator, boolean ignoreZScript, boolean ignoreXel)` | Constructors with full control, including separator, whether to search zscript and xel variables

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `alert​(java.lang.String m)` |
    `void` | `didActivate​(Component comp)` | Called when a session has just been activated (and its value has been deserialized).
    `void` | `doAfterCompose​(T comp)` | Auto wire accessible variables of the specified component into a controller Java object; a subclass that override this method should remember to call super.doAfterCompose(comp) or it will not work.
    `protected Page` | `getPage()` | Returns the current page.
    `java.lang.Object` | `willClone​(Component comp)` | Internal use only.
    `void` | `willPassivate​(Component comp)` | Called when a session is about to be passivated (and then serialize its value).

    - ### Methods inherited from class org.zkoss.zk.ui.util.GenericComposer

      `doBeforeCompose, doBeforeComposeChildren, doCatch, doFinally`

    - ### Methods inherited from class org.zkoss.zk.ui.event.GenericEventListener

      `bindComponent, getController, onEvent, unbindComponent`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### self

          protected transient T extends Component self

      Implicit Object; the applied component itself.
      Since:
        3.0.7

    - #### spaceOwner

          protected transient IdSpace spaceOwner

      Implicit Object; the space owner of the applied component.
      Since:
        3.0.7

    - #### page

          protected transient Page page

      Implicit Object; the page.
      Since:
        3.0.7

    - #### desktop

          protected transient Desktop desktop

      Implicit Object; the desktop.
      Since:
        3.0.7

    - #### session

          protected transient Session session

      Implicit Object; the session.
      Since:
        3.0.7

    - #### application

          protected transient WebApp application

      Implicit Object; the web application.
      Since:
        3.0.7

    - #### componentScope

          protected transient java.util.Map<java.lang.String,​java.lang.Object> componentScope

      Implicit Object; a map of attributes defined in the applied component.
      Since:
        3.0.7

    - #### spaceScope

          protected transient java.util.Map<java.lang.String,​java.lang.Object> spaceScope

      Implicit Object; a map of attributes defined in the ID space contains the applied component.
      Since:
        3.0.7

    - #### pageScope

          protected transient java.util.Map<java.lang.String,​java.lang.Object> pageScope

      Implicit Object; a map of attributes defined in the page.
      Since:
        3.0.7

    - #### desktopScope

          protected transient java.util.Map<java.lang.String,​java.lang.Object> desktopScope

      Implicit Object; a map of attributes defined in the desktop.
      Since:
        3.0.7

    - #### sessionScope

          protected transient java.util.Map<java.lang.String,​java.lang.Object> sessionScope

      Implicit Object; a map of attributes defined in the session.
      Since:
        3.0.7

    - #### applicationScope

          protected transient java.util.Map<java.lang.String,​java.lang.Object> applicationScope

      Implicit Object; a map of attributes defined in the web application.
      Since:
        3.0.7

    - #### requestScope

          protected transient java.util.Map<java.lang.String,​java.lang.Object> requestScope

      Implicit Object; a map of attributes defined in the request.
      Since:
        3.0.7

    - #### execution

          protected transient Execution execution

      Implicit Object; the current execution.
      Since:
        3.0.7

    - #### arg

          protected transient java.util.Map<?,​?> arg

      Implicit Object; the arg argument passed to the createComponents method. It is never null.
      Since:
        3.0.8

    - #### param

          protected transient java.util.Map<java.lang.String,​java.lang.String[]> param

      Implicit Object; the param argument passed from the http request.
      Since:
        3.6.1

    - #### _separator

          protected char _separator

      The separator used to separate the component ID and event name. By default, it is '$'. For Groovy and other environment that '$' is not applicable, you can specify '_'.

  - ### Constructor Detail

    - #### GenericAutowireComposer

          protected GenericAutowireComposer()

      The default constructor.

      It is a shortcut of `GenericAutowireComposer('$', !"true".equals(Library.getProperty("org.zkoss.zk.ui.composer.autowire.zscript")), !"true".equals(Library.getProperty("org.zkoss.zk.ui.composer.autowire.xel")))`.

      In other words, whether to ignore variables defined in ZSCRIPT and XEL depends on the library variables called `org.zkoss.zk.ui.composer.autowire.zscript` and `org.zkoss.zk.ui.composer.autowire.xel`. Furthermore, if not specified, their values are default to false, i.e., they shall not be wired (i.e., shall be ignored)

      If you want to control whether to wire ZSCRIPT's or XEL's variable explicitly, you could use `GenericAutowireComposer(char,boolean,boolean)` instead.

      ## Version Difference

      ZK 5.0 and earlier, this constructor is the same as `GenericAutowireComposer('$', false, false)`
      In other words, it is default to wire (i.e., shall not ignore).

    - #### GenericAutowireComposer

          protected GenericAutowireComposer​(char separator)

      Constructor with a custom separator. The separator is used to separate the component ID and event name. By default, it is '$'. For Groovy and other environment that '$' is not applicable, you can specify '_'.

      It is a shortcut of `GenericAutowireComposer('$', !"true".equals(Library.getProperty("org.zkoss.zk.ui.composer.autowire.zscript")), !"true".equals(Library.getProperty("org.zkoss.zk.ui.composer.autowire.xel")))`.

      In other words, whether to ignore variables defined in ZSCRIPT and XEL depends on the library variables called `org.zkoss.zk.ui.composer.autowire.zscript` and `org.zkoss.zk.ui.composer.autowire.xel`. Furthermore, if not specified, their values are default to false, i.e., they shall not be wired (i.e., shall be ignored)

      If you want to control whether to wire ZSCRIPT's or XEL's variable explicitly, you could use `GenericAutowireComposer(char,boolean,boolean)` instead.

      ## Version Difference

      ZK 5.0 and earlier, this constructor is the same as `GenericAutowireComposer('$', false, false)`
      In other words, it is default to wire (i.e., shall not ignore).

      Parameters:
        `separator` - the separator used to separate the component ID and event name. Refer to `_separator` for details.
      Since:
        3.6.0

    - #### GenericAutowireComposer

          protected GenericAutowireComposer​(char separator,
                                            boolean ignoreZScript,
                                            boolean ignoreXel)

      Constructors with full control, including separator, whether to search zscript and xel variables
      Parameters:
        `separator` - the separator used to separate the component ID and event name. Refer to `_separator` for details.
        `ignoreZScript` - whether to ignore variables defined in zscript when wiring a member.
        `ignoreXel` - whether to ignore variables defined in variable resolver (`Page.addVariableResolver(org.zkoss.xel.VariableResolver)`) when wiring a member.
      Since:
        5.0.3

  - ### Method Detail

    - #### getPage

          protected Page getPage()

      Returns the current page.
      Overrides:
        `getPage` in class `GenericComposer<T extends Component>`
      Since:
        5.0.10

    - #### doAfterCompose

          public void doAfterCompose​(T comp)
                              throws java.lang.Exception

      Auto wire accessible variables of the specified component into a controller Java object; a subclass that override this method should remember to call super.doAfterCompose(comp) or it will not work.
      Specified by:
        `doAfterCompose` in interface `Composer<T extends Component>`
      Overrides:
        `doAfterCompose` in class `GenericComposer<T extends Component>`
      Parameters:
        `comp` - the component has been composed
      Throws:
        `java.lang.Exception`

    - #### alert

          protected void alert​(java.lang.String m)

    - #### willClone

          public java.lang.Object willClone​(Component comp)

      Internal use only. Call-back method of CloneComposerListener. You shall not call this method directly. Clone this Composer when its applied component is cloned.
      Specified by:
        `willClone` in interface `ComponentCloneListener`
      Parameters:
        `comp` - the clone of the applied component
      Returns:
        A clone of this Composer.
      Since:
        3.5.2

    - #### didActivate

          public void didActivate​(Component comp)

      Description copied from interface: `ComponentActivationListener`
      Called when a session has just been activated (and its value has been deserialized).
      Specified by:
        `didActivate` in interface `ComponentActivationListener`

    - #### willPassivate

          public void willPassivate​(Component comp)

      Description copied from interface: `ComponentActivationListener`
      Called when a session is about to be passivated (and then serialize its value).
      Specified by:
        `willPassivate` in interface `ComponentActivationListener`