Package org.zkoss.bind

## Interface Binder

- All Known Subinterfaces:
    `ClientBinder`
  All Known Implementing Classes:
    `AnnotateBinder`, `AnnotateBinderEx`, `BinderImpl`, `DefaultBinder`, `DefaultClientBinder`

      public interface Binder

  The Binder that do the data binding things.
  Since:
    6.0.0
  Author:
    henrichen, dennischen

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `ACCESS` | Attribute of `ZKBIND` annotation, the access direction: can be "both", "save", "load"; default to "load" if not found
    `static int` | `COMMAND_FAIL_VALIDATE` | Indicates the doing command is failure with some validation errors.
    `static int` | `COMMAND_SUCCESS` | Indicates the doing command is successful.
    `static java.lang.String` | `CONVERTER` | Attribute of `ZKBIND` annotation, the system converter for special properties. e.g.
    `static java.lang.String` | `LOAD_EVENT` | Attribute of `ZKBIND` annotation, the load trigger event; meaningful only when ACCESS is "both" or "load" or not found(default to "load").
    `static java.lang.String` | `LOAD_REPLACEMENT` | Attribute of `ZKBIND` annotation, the load replacement ; e.g. value of textbox, it loads to rawValue
    `static java.lang.String` | `LOAD_TYPE` | Attribute of `ZKBIND` annotation, the type of attribute for loading; e.g. rawValue of textbox is java.lang.String
    `static java.lang.String` | `RENDERER` | Attribute of `ZKBIND` annotation, the special renderer for binding
    `static java.lang.String` | `SAVE_EVENT` | Attribute of `ZKBIND` annotation, the save trigger event; meaningful only when ACCESS is "both" or "save".
    `static java.lang.String` | `SAVE_REPLACEMENT` | Attribute of `ZKBIND` annotation, the save replacement ; e.g. selectedItem of selectbox, it save the value selectedIndex (via converter) to bean
    `static java.lang.String` | `VALIDATOR` | Attribute of `ZKBIND` annotation, the system validator for special properties.
    `static java.lang.String` | `ZKBIND` | Component annotation of ZKBind

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addChildrenInitBinding​(Component comp, java.lang.String initExpr, java.util.Map<java.lang.String,​java.lang.Object> initArgs, java.lang.String converterExpr, java.util.Map<java.lang.String,​java.lang.Object> converterArgs)` | init children of a component by an expression, it only execute once
    `void` | `addChildrenLoadBindings​(Component comp, java.lang.String loadExpr, java.lang.String[] beforeCmds, java.lang.String[] afterCmds, java.util.Map<java.lang.String,​java.lang.Object> bindingArgs, java.lang.String converterExpr, java.util.Map<java.lang.String,​java.lang.Object> converterArgs)` | Add new children-load-bindings.
    `void` | `addCommandBinding​(Component comp, java.lang.String evtnm, java.lang.String commandExpr, java.util.Map<java.lang.String,​java.lang.Object> commandArgs)` | Add a new command binding.
    `void` | `addFormInitBinding​(Component comp, java.lang.String id, java.lang.String initExpr, java.util.Map<java.lang.String,​java.lang.Object> initArgs)` | init a component form by expression, it only execute once
    `void` | `addFormLoadBindings​(Component comp, java.lang.String id, java.lang.String loadExpr, java.lang.String[] beforeCmds, java.lang.String[] afterCmds, java.util.Map<java.lang.String,​java.lang.Object> bindingArgs)` | Add new form-load-bindings.
    `void` | `addFormSaveBindings​(Component comp, java.lang.String id, java.lang.String saveExpr, java.lang.String[] beforeCmds, java.lang.String[] afterCmds, java.util.Map<java.lang.String,​java.lang.Object> bindingArgs, java.lang.String validatorExpr, java.util.Map<java.lang.String,​java.lang.Object> validatorArgs)` | Add new form-save-bindings.
    `void` | `addGlobalCommandBinding​(Component comp, java.lang.String evtnm, java.lang.String commandExpr, java.util.Map<java.lang.String,​java.lang.Object> commandArgs)` | Add a new global-command binding.
    `void` | `addPropertyInitBinding​(Component comp, java.lang.String attr, java.lang.String initExpr, java.util.Map<java.lang.String,​java.lang.Object> initArgs, java.lang.String converterExpr, java.util.Map<java.lang.String,​java.lang.Object> converterArgs)` | init a component property by a expression, it only execute once
    `void` | `addPropertyLoadBindings​(Component comp, java.lang.String attr, java.lang.String loadExpr, java.lang.String[] beforeCmds, java.lang.String[] afterCmds, java.util.Map<java.lang.String,​java.lang.Object> bindingArgs, java.lang.String converterExpr, java.util.Map<java.lang.String,​java.lang.Object> converterArgs)` | Add new property-load-bindings.
    `void` | `addPropertySaveBindings​(Component comp, java.lang.String attr, java.lang.String saveExpr, java.lang.String[] beforeCmds, java.lang.String[] afterCmds, java.util.Map<java.lang.String,​java.lang.Object> bindingArgs, java.lang.String converterExpr, java.util.Map<java.lang.String,​java.lang.Object> converterArgs, java.lang.String validatorExpr, java.util.Map<java.lang.String,​java.lang.Object> validatorArgs)` | Add new property-save-bindings.
    `void` | `addReferenceBinding​(Component comp, java.lang.String attr, java.lang.String loadExpr, java.util.Map<java.lang.String,​java.lang.Object> bindingArgs)` | Add a new reference-binding.
    `void` | `destroy​(Component root, java.lang.Object viewModel)` | Destroys the binder with a root component and viewModel object.
    `Converter` | `getConverter​(java.lang.String name)` | Returns the _converter of the given _converter name.
    `BindEvaluatorX` | `getEvaluatorX()` | Returns the `BindEvaluatorX` used by this Binder.
    `Validator` | `getValidator​(java.lang.String name)` | Returns the _validator of the given _validator name.
    `Component` | `getView()` | Returns associated root component of this binder.
    `java.lang.Object` | `getViewModel()` | Returns associated ViewModel of this binder.
    `void` | `init​(Component root, java.lang.Object viewModel, java.util.Map<java.lang.String,​java.lang.Object> initArgs)` | Initializes the binder with a root component and viewModel object.
    `void` | `loadComponent​(Component comp, boolean loadinit)` | Load the load-binding of the component.
    `void` | `notifyChange​(java.lang.Object bean, java.lang.String property)` | Notify change of the property.
    `void` | `postCommand​(java.lang.String command, java.util.Map<java.lang.String,​java.lang.Object> args)` | post command this binder, binder will queue the command, and fired later.
    `void` | `removeBindings​(java.util.Set<Component> comps)` | Remove all managed bindings that associated with the specified components.
    `void` | `removeBindings​(Component comp)` | Remove all managed bindings that associated with the specified component.
    `void` | `removeBindings​(Component comp, java.lang.String key)` | Remove all managed Binding that associated with the specified component and attribute name, event name, or form id.
    `int` | `sendCommand​(java.lang.String command, java.util.Map<java.lang.String,​java.lang.Object> args)` | send command fired to this binder and process the command immediately
    `void` | `setPhaseListener​(PhaseListener listener)` | Sets the associated phase listener to intervene the binding life cycle.
    `void` | `setTemplate​(Component comp, java.lang.String attr, java.lang.String templateExpr, java.util.Map<java.lang.String,​java.lang.Object> templateArgs)` | set template to a component property by an expression
    `void` | `setViewModel​(java.lang.Object viewModel)` | Sets associated ViewModel of this binder.

- - ### Field Detail

    - #### ZKBIND

          static final java.lang.String ZKBIND

      Component annotation of ZKBind
      See Also:
        Constant Field Values

    - #### RENDERER

          static final java.lang.String RENDERER

      Attribute of `ZKBIND` annotation, the special renderer for binding
      See Also:
        Constant Field Values

    - #### LOAD_EVENT

          static final java.lang.String LOAD_EVENT

      Attribute of `ZKBIND` annotation, the load trigger event; meaningful only when ACCESS is "both" or "load" or not found(default to "load").
      See Also:
        Constant Field Values

    - #### SAVE_EVENT

          static final java.lang.String SAVE_EVENT

      Attribute of `ZKBIND` annotation, the save trigger event; meaningful only when ACCESS is "both" or "save".
      See Also:
        Constant Field Values

    - #### ACCESS

          static final java.lang.String ACCESS

      Attribute of `ZKBIND` annotation, the access direction: can be "both", "save", "load"; default to "load" if not found
      See Also:
        Constant Field Values

    - #### CONVERTER

          static final java.lang.String CONVERTER

      Attribute of `ZKBIND` annotation, the system converter for special properties. e.g. SelectedItem in listbox. see SelectedListitemConverter.java
      See Also:
        Constant Field Values

    - #### VALIDATOR

          static final java.lang.String VALIDATOR

      Attribute of `ZKBIND` annotation, the system validator for special properties.
      See Also:
        Constant Field Values

    - #### LOAD_REPLACEMENT

          static final java.lang.String LOAD_REPLACEMENT

      Attribute of `ZKBIND` annotation, the load replacement ; e.g. value of textbox, it loads to rawValue
      See Also:
        Constant Field Values

    - #### LOAD_TYPE

          static final java.lang.String LOAD_TYPE

      Attribute of `ZKBIND` annotation, the type of attribute for loading; e.g. rawValue of textbox is java.lang.String
      See Also:
        Constant Field Values

    - #### SAVE_REPLACEMENT

          static final java.lang.String SAVE_REPLACEMENT

      Attribute of `ZKBIND` annotation, the save replacement ; e.g. selectedItem of selectbox, it save the value selectedIndex (via converter) to bean
      See Also:
        Constant Field Values

    - #### COMMAND_SUCCESS

          static final int COMMAND_SUCCESS

      Indicates the doing command is successful.
      Since:
        8.0.1
      See Also:
        Constant Field Values

    - #### COMMAND_FAIL_VALIDATE

          static final int COMMAND_FAIL_VALIDATE

      Indicates the doing command is failure with some validation errors.
      Since:
        8.0.1
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### init

          void init​(Component root,
                    java.lang.Object viewModel,
                    java.util.Map<java.lang.String,​java.lang.Object> initArgs)

      Initializes the binder with a root component and viewModel object. You should never call this if you use `AnnotateBinder` and zk annotation
      Parameters:
        `root` - root component of binder
        `viewModel` - viewModel object
        `initArgs` - args key-value pairs for initial, nullable
      Since:
        6.0.1

    - #### destroy

          void destroy​(Component root,
                       java.lang.Object viewModel)

      Destroys the binder with a root component and viewModel object. You should never call this if you use `AnnotateBinder` and zk annotation
      Parameters:
        `root` - root component of binder
        `viewModel` - viewModel object
      Since:
        8.5.2

    - #### loadComponent

          void loadComponent​(Component comp,
                             boolean loadinit)

      Load the load-binding of the component.
      By calling this method, all load-bindings in the component (including load-bindings in its descendant) will reload the value to components.
      Parameters:
        `comp` - the component to reload
        `loadinit` - true if should also load the init-binding

    - #### getEvaluatorX

          BindEvaluatorX getEvaluatorX()

      Returns the `BindEvaluatorX` used by this Binder.
      Returns:
        the EvaluatorX.

    - #### addCommandBinding

          void addCommandBinding​(Component comp,
                                 java.lang.String evtnm,
                                 java.lang.String commandExpr,
                                 java.util.Map<java.lang.String,​java.lang.Object> commandArgs)

      Add a new command binding.
      Parameters:
        `comp` - the associated component
        `evtnm` - the associated component event name
        `commandExpr` - the command expression
        `commandArgs` - other key-value pairs pairs for command

    - #### addGlobalCommandBinding

          void addGlobalCommandBinding​(Component comp,
                                       java.lang.String evtnm,
                                       java.lang.String commandExpr,
                                       java.util.Map<java.lang.String,​java.lang.Object> commandArgs)

      Add a new global-command binding.
      Parameters:
        `comp` - the associated component
        `evtnm` - the associated component event name
        `commandExpr` - the command expression
        `commandArgs` - other key-value pairs pairs for command

    - #### setTemplate

          void setTemplate​(Component comp,
                           java.lang.String attr,
                           java.lang.String templateExpr,
                           java.util.Map<java.lang.String,​java.lang.Object> templateArgs)

      set template to a component property by an expression
      Parameters:
        `comp` - the associated component, must not null
        `attr` - the associated attribute of the component; ex label, style, must not null
        `templateExpr` - template expression, must not null
        `templateArgs` - args key-value pairs for template, nullable

    - #### addPropertyInitBinding

          void addPropertyInitBinding​(Component comp,
                                      java.lang.String attr,
                                      java.lang.String initExpr,
                                      java.util.Map<java.lang.String,​java.lang.Object> initArgs,
                                      java.lang.String converterExpr,
                                      java.util.Map<java.lang.String,​java.lang.Object> converterArgs)

      init a component property by a expression, it only execute once
      Parameters:
        `comp` - the associated component, must not null
        `attr` - the associated attribute of the component; ex label, style, must not null
        `initExpr` - init expression, must not null
        `initArgs` - args key-value pairs for initial, nullable
        `converterExpr` - the converter expression, nullable
        `converterArgs` - args key-value pairs for converter, nullable

    - #### addPropertyLoadBindings

          void addPropertyLoadBindings​(Component comp,
                                       java.lang.String attr,
                                       java.lang.String loadExpr,
                                       java.lang.String[] beforeCmds,
                                       java.lang.String[] afterCmds,
                                       java.util.Map<java.lang.String,​java.lang.Object> bindingArgs,
                                       java.lang.String converterExpr,
                                       java.util.Map<java.lang.String,​java.lang.Object> converterArgs)

      Add new property-load-bindings. It creates a prompt|conditional property-load-binding depends on beforeCmds and afterCmds. If both beforeCmds and afterCmds are null or empty, it create a prompt binding.
      Parameters:
        `comp` - the associated component, must not null
        `attr` - the associated attribute of the component; ex label, style, must not null
        `loadExpr` - load expression, must not null
        `beforeCmds` - load before these commands, the command here is not a EL expression. nullable
        `afterCmds` - load after these commands, the command here is not a EL expression. nullable
        `bindingArgs` - args key-value pairs for this binding, nullable
        `converterExpr` - the converter expression, nullable
        `converterArgs` - args key-value pairs for converter, nullable

    - #### addPropertySaveBindings

          void addPropertySaveBindings​(Component comp,
                                       java.lang.String attr,
                                       java.lang.String saveExpr,
                                       java.lang.String[] beforeCmds,
                                       java.lang.String[] afterCmds,
                                       java.util.Map<java.lang.String,​java.lang.Object> bindingArgs,
                                       java.lang.String converterExpr,
                                       java.util.Map<java.lang.String,​java.lang.Object> converterArgs,
                                       java.lang.String validatorExpr,
                                       java.util.Map<java.lang.String,​java.lang.Object> validatorArgs)

      Add new property-save-bindings. It creates a prompt|conditional property-save-binding depends on beforeCmds and afterCmds. If both beforeCmds and afterCmds are null or empty, it create a prompt binding.
      Parameters:
        `comp` - the associated component, must not null
        `attr` - the associated attribute of the component; ex value, check, must not null
        `saveExpr` - save expression, nullable
        `beforeCmds` - save before these commands, the command here is not a EL expression. nullable
        `afterCmds` - save after these commands, the command here is not a EL expression. nullable
        `bindingArgs` - args key-value pairs for this binding, nullable
        `converterExpr` - the converter expression, nullable
        `converterArgs` - args key-value pairs for converter, nullable
        `validatorExpr` - the converter expression, nullable
        `validatorArgs` - args key-value pairs for validator, nullable

    - #### addFormInitBinding

          void addFormInitBinding​(Component comp,
                                  java.lang.String id,
                                  java.lang.String initExpr,
                                  java.util.Map<java.lang.String,​java.lang.Object> initArgs)

      init a component form by expression, it only execute once
      Parameters:
        `comp` - the associated component, must not null
        `id` - the form id, must not null
        `initExpr` - init expression, nullable
        `initArgs` - args key-value pairs for this init, nullable

    - #### addFormLoadBindings

          void addFormLoadBindings​(Component comp,
                                   java.lang.String id,
                                   java.lang.String loadExpr,
                                   java.lang.String[] beforeCmds,
                                   java.lang.String[] afterCmds,
                                   java.util.Map<java.lang.String,​java.lang.Object> bindingArgs)

      Add new form-load-bindings. It create a prompt|conditional form-load-binding depends on beforeCmds and afterCmds. If both beforeCmds and afterCmds are null or empty, it create a prompt binding.
      Parameters:
        `comp` - the associated component, must not null
        `id` - the form id, must not null
        `loadExpr` - load expression, nullable
        `beforeCmds` - load before these commands, the command here is not a EL expression. nullable
        `afterCmds` - load after these commands, the command here is not a EL expression. nullable
        `bindingArgs` - args key-value pairs for this binding, nullable

    - #### addFormSaveBindings

          void addFormSaveBindings​(Component comp,
                                   java.lang.String id,
                                   java.lang.String saveExpr,
                                   java.lang.String[] beforeCmds,
                                   java.lang.String[] afterCmds,
                                   java.util.Map<java.lang.String,​java.lang.Object> bindingArgs,
                                   java.lang.String validatorExpr,
                                   java.util.Map<java.lang.String,​java.lang.Object> validatorArgs)

      Add new form-save-bindings. It create a conditional form-save-binding depends on beforeCmds and afterCmds. Since form-save-binding is always triggered by command, if both beforeCmds and afterCmds are null or empty, it throws an exception.
      Parameters:
        `comp` - the associated component, must not null
        `id` - the form id, must not null
        `saveExpr` - save expression, nullable
        `beforeCmds` - save before these commands, the command here is not a EL expression. nullable
        `afterCmds` - save after these commands, the command here is not a EL expression. nullable
        `bindingArgs` - args key-value pairs for this binding, nullable
        `validatorExpr` - the converter expression, nullable
        `validatorArgs` - args key-value pairs for validator, nullable
      Throws:
        `java.lang.IllegalArgumentException` - if beforeCmds or afterCmds are both null or empty

    - #### addChildrenInitBinding

          void addChildrenInitBinding​(Component comp,
                                      java.lang.String initExpr,
                                      java.util.Map<java.lang.String,​java.lang.Object> initArgs,
                                      java.lang.String converterExpr,
                                      java.util.Map<java.lang.String,​java.lang.Object> converterArgs)

      init children of a component by an expression, it only execute once
      Parameters:
        `comp` - the associated component, must not null
        `initExpr` - init expression, must not null
        `initArgs` - args key-value pairs for initial, nullable
        `converterExpr` - the converter expression, nullable
        `converterArgs` - args key-value pairs for converter, nullable
      Since:
        6.0.1

    - #### addChildrenLoadBindings

          void addChildrenLoadBindings​(Component comp,
                                       java.lang.String loadExpr,
                                       java.lang.String[] beforeCmds,
                                       java.lang.String[] afterCmds,
                                       java.util.Map<java.lang.String,​java.lang.Object> bindingArgs,
                                       java.lang.String converterExpr,
                                       java.util.Map<java.lang.String,​java.lang.Object> converterArgs)

      Add new children-load-bindings. It creates a prompt|conditional children-load-binding depends on beforeCmds and afterCmds. If both beforeCmds and afterCmds are null or empty, it create a prompt binding.
      Parameters:
        `comp` - the associated component, must not null
        `loadExpr` - load expression, must not null
        `beforeCmds` - load before these commands, the command here is not a EL expression. nullable
        `afterCmds` - load after these commands, the command here is not a EL expression. nullable
        `bindingArgs` - args key-value pairs for this binding, nullable
        `converterExpr` - the converter expression, nullable
        `converterArgs` - args key-value pairs for converter, nullable
      Since:
        6.0.1

    - #### addReferenceBinding

          void addReferenceBinding​(Component comp,
                                   java.lang.String attr,
                                   java.lang.String loadExpr,
                                   java.util.Map<java.lang.String,​java.lang.Object> bindingArgs)

      Add a new reference-binding. It creates an attribute as the reference of the expression in the component.
      Parameters:
        `comp` - the associated component, must not null
        `attr` - the name of reference that stored in the component; ex myval, must not null
        `loadExpr` - load expression, must not null
        `bindingArgs` - args key-value pairs for this binding, nullable
      Since:
        6.0.1

    - #### removeBindings

          void removeBindings​(Component comp)

      Remove all managed bindings that associated with the specified component.
      Parameters:
        `comp` -

    - #### removeBindings

          void removeBindings​(java.util.Set<Component> comps)

      Remove all managed bindings that associated with the specified components.
      Parameters:
        `comps` -
      Since:
        7.0.2

    - #### removeBindings

          void removeBindings​(Component comp,
                              java.lang.String key)

      Remove all managed Binding that associated with the specified component and attribute name, event name, or form id.
      Parameters:
        `comp` - the associated component
        `key` - the associated attribute name, event name, or form id

    - #### getConverter

          Converter getConverter​(java.lang.String name)

      Returns the _converter of the given _converter name.
      Parameters:
        `name` - _converter name
      Returns:
        the _converter of the given _converter name.

    - #### getValidator

          Validator getValidator​(java.lang.String name)

      Returns the _validator of the given _validator name.
      Parameters:
        `name` - _validator name
      Returns:
        the _validator of the given _validator name.

    - #### notifyChange

          void notifyChange​(java.lang.Object bean,
                            java.lang.String property)

      Notify change of the property.
      Parameters:
        `bean` - the backing bean object.
        `property` - the property of the bean that change the value

    - #### sendCommand

          int sendCommand​(java.lang.String command,
                          java.util.Map<java.lang.String,​java.lang.Object> args)

      send command fired to this binder and process the command immediately
      Parameters:
        `command` - command name
        `args` - , arguments when notifying this command, it will be passed as a arguments of execution method of vm
      Returns:
        the result of the doCommand, COMMAND_SUCCESS or COMMAND_FAIL_VALIDATE (since 8.0.1)

    - #### postCommand

          void postCommand​(java.lang.String command,
                           java.util.Map<java.lang.String,​java.lang.Object> args)

      post command this binder, binder will queue the command, and fired later.
      Parameters:
        `command` - command name
        `args` - , arguments when notifying this command, it will be passed as a arguments of execution method of vm

    - #### getViewModel

          java.lang.Object getViewModel()

      Returns associated ViewModel of this binder.
      Returns:
        associated ViewModel of this binder.

    - #### setViewModel

          void setViewModel​(java.lang.Object viewModel)

      Sets associated ViewModel of this binder.
      Parameters:
        `viewModel` - the associated view model of this binder.

    - #### setPhaseListener

          void setPhaseListener​(PhaseListener listener)

      Sets the associated phase listener to intervene the binding life cycle.
      Parameters:
        `listener` - the associated phase listener.

    - #### getView

          Component getView()

      Returns associated root component of this binder.
      Returns:
        associated root component of this binder.