Package com.orchestranetworks.ui

# Class UIBeanEditor

java.lang.Object
com.orchestranetworks.ui.UIBeanEditor

Direct Known Subclasses:
  `UIBeanEditorV4`

@Deprecated public abstract class UIBeanEditor extends Object
Deprecated.
From 5.8.0, please use the new API `UICustomWidget` instead.
Abstract class for customizing UI beans on master data. A UI bean can display an element differently and/or modify its value.

### Definition in the data model

A specific UI bean can be associated with any element declaration that is a terminal value or under a terminal value (see `SchemaNode.isTerminalValue()`). The UI bean must be declared under the element `xs:annotation/xs:appinfo`:

>      <xs:annotation>
>        <xs:appinfo>
>          <osd:uiBean class="com.foo.MyUIBean" />
>        </xs:appinfo>
>      </xs:annotation>

where `com.foo.MyUIBean` is the fully qualified name of a class implementing this interface. The declaration may also use parameters:

>      <osd:uiBean class="com.foo.MyUIBean">
>             <param1>...</param1>
>             <param2>...</param2>
>      </osd:uiBean>

where `param1` and `param2` are JavaBean properties of `com.foo.MyUIBean` class.

For more information, see the JavaBean specification.

### Data model definition through `BeanInfo` declaration

This option is only necessary to avoid repeating the data model declaration `<osd:uiBean class="...">` each time a JavaBean class is referenced in a data model.

When a data model node is associated with a JavaBean (by attribute `osd:class="..."`), it is possible to specify the association between the JavaBean and its default UIBeanEditor once. This association is declared using the standard `BeanInfo` extension class. This class extends `java.beansSimpleBeanInfo` and must implement the following method:

     public BeanDescriptor getBeanDescriptor()
     {
            return new BeanDescriptor(MyBean.class, UIMyBean.class);
     }

### Life cycle

1. When a session of EBX® generates HTTP response including a bean editor, the specified class is instantiated using its default constructor and the JavaBean property setters are called (in the example above, `setParam1(...)` and `setParam2(...)`). Then, one of the methods `addFor...` is called.
2. When the page generated in the previous step is submitted and the server receives the corresponding HTTP request, this is the same instance that is responsible for handling the parameters of the HTTP request, supplying the data context and checking its integrity. The user input validation steps are detailed in the method `shallValidateInput(UIRequestContext)`.

### Multi-threading

EBX® container ensures that an instance of this class is executed by no more than one thread at a given time.

### Behavior for aggregated lists

If this editor is applied to a complex node with `maxOccurs > 1`, it is instantiated for the `List` and also for each element (`Occurrence`) in the list.

In order to manage a special behavior for the whole `List`, the developer can override the method `addList(UIResponseContext)` such as:

     public void addList(UIResponseContext aResponse)
     {
            aResponse.add("<ol>");

            List theList = (List) aResponse.getValue();

            if (theList == null || theList.isEmpty())
                    theList = new ArrayList(3);

            for (int i = 0; i < theList.size(); i++)
            {
                    aResponse.add("<li>");

                    Path occurrencePath = aResponse.getPathForListOccurrence(i);

                    UIWidget bestMatchingWidget = aResponse.newBestMatching(occurrencePath);
                    aResponse.addWidget(bestMatchingWidget);

                    aResponse.add("</li>");
            }

            aResponse.add("</ol>");
     }

In this example, the `addList` method will draw a simple HTML ordered list (`<ol> <li>`) and build occurrence paths to each of its elements. The `aResponse.addWidget(...)` of the `best matching widget` for each occurrence will call `addForEdit(UIResponseContext)` or `addForDisplay(UIResponseContext)` (depending on the current rendering mode) of the same UI Bean, but instantiated in the occurrence context.

If `addList` is not overridden, `addForEdit` or `addForDisplay` will be called at the list and occurrence levels for groups, and at the occurrence level only for fields (the whole list is managed by default).

Obviously, it is possible to request the default drawing of the whole list by using the best matching widget in the `addList` method such as:

     public void addList(UIResponseContext aResponse)
     {
            aResponse.addWidget(aResponse.newBestMatching(Path.SELF));
     }

In this case, the user only manages the occurrence level with the methods `addForEdit/Display`.

It is possible to manage input validation at list level by implementing `shallValidateInputList(UIRequestContext)` or `validateInputList(UIRequestContext)`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UIBeanEditor()`
  Deprecated.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `addForDisplay(UIResponseContext aResponse)`
  Deprecated.
  Adds HTML or DHTML content to the HTTP response, so as to display the current element's value within the record form, when the element is read-only.
  `void`
  `addForDisplayInTable(UIResponseContext aResponse)`
  Deprecated.
  Adds HTML or DHTML content to the HTTP response, so as to display the current element's value within the tabular view.
  `abstract void`
  `addForEdit(UIResponseContext aResponse)`
  Deprecated.
  Adds HTML or DHTML content to HTTP response, so that the end user can edit the current element's value within the record form.
  `void`
  `addForEditInTable(UIResponseContext aResponse)`
  Deprecated.
  Adds HTML or DHTML content to HTTP response, so that the end user can edit the current element's value within the tabular view.
  `void`
  `addForNull(UIResponseContext aResponse)`
  Deprecated.
  Adds HTML or DHTML content to the HTTP response, so as to display the fact that the current value is not defined (`null`) in cases when the field is in read-only mode.
  `void`
  `addForNullInTable(UIResponseContext aResponse)`
  Deprecated.
  Adds HTML or DHTML content to the HTTP response, used to denote that the current value is not defined (`null`) in the cell of the table view in cases when the field is in read-only mode.
  `void`
  `addForPrint(UIResponseContext aResponse)`
  Deprecated.
  This method is no longer invoked.
  `void`
  `addList(UIResponseContext aResponse)`
  Deprecated.
  Overrides to add HTML or DHTML content to the HTTP response, so as to display or edit the current element's whole `List` within the record form.
  `UserMessage`
  `getMessageForSettingNull(UIResponseContext aResponse)`
  Deprecated.
  Returns the message to display in the user interface when setting the value of the associated element to `null` .
  `UserMessage`
  `getMessageForSettingValue(UIResponseContext aResponse)`
  Deprecated.
  Returns the message to display in the user interface when editing a value of the associated element; the action is available when the current value is undefined (`null`) in the user interface.
  `boolean`
  `shallValidateInput(UIRequestContext aRequest)`
  Deprecated.
  Returns `true` if the user input associated with this editor will be validated; returns `false` if the local user input related to the current UI bean is ignored beyond the execution of this method.
  `boolean`
  `shallValidateInputList(UIRequestContext aRequest)`
  Deprecated.
  Same as `shallValidateInput` for an aggregated list.
  `void`
  `validateInput(UIRequestContext aRequest)`
  Deprecated.
  Offers the opportunity to perform custom validation upon user input.
  `void`
  `validateInputList(UIRequestContext aRequest)`
  Deprecated.
  Does the same thing as `validateInput` for an aggregated list.

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

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

- ## Constructor Details

  - ### UIBeanEditor

    public UIBeanEditor()
    Deprecated.

- ## Method Details

  - ### addForDisplay

    public abstract void addForDisplay(UIResponseContext aResponse)
    Deprecated.
    Adds HTML or DHTML content to the HTTP response, so as to display the current element's value within the record form, when the element is read-only.

    If the current element is an aggregated list, the method `addList(UIResponseContext)` is invoked first.

  - ### addForDisplayInTable

    public void addForDisplayInTable(UIResponseContext aResponse)
    Deprecated.
    Adds HTML or DHTML content to the HTTP response, so as to display the current element's value within the tabular view.

    The default implementation displays a generic "see details" message.

    Limitation: the string displayed in the table will not be taken into account by searches and filters.

    See Also:
      - `addForDisplay(UIResponseContext)`

  - ### addForEdit

    public abstract void addForEdit(UIResponseContext aResponse)
    Deprecated.
    Adds HTML or DHTML content to HTTP response, so that the end user can edit the current element's value within the record form.

    If the current element is an aggregated list, the method `addList(UIResponseContext)` is first invoked.

  - ### addForEditInTable

    public void addForEditInTable(UIResponseContext aResponse)
    Deprecated.
    Adds HTML or DHTML content to HTTP response, so that the end user can edit the current element's value within the tabular view.

    Note: Since version 5.0.0, this method is no longer invoked due to a limitation. This method may be reenabled in a future version.

    Default implementation does not provide an editor, it displays a generic "see details" message.

    See Also:
      - `addForDisplayInTable(UIResponseContext)`
      - `addForEdit(UIResponseContext)`

  - ### addForNull

    public void addForNull(UIResponseContext aResponse)
    Deprecated.
    Adds HTML or DHTML content to the HTTP response, so as to display the fact that the current value is not defined (`null`) in cases when the field is in read-only mode.

    Default implementation displays a message indicating that the value of the associated node is undefined.

    Known limitations:

    This method is ignored if this `UIBeanEditor` is:

    - defined on a node under a terminal node (other than tables),
    - displayed in a tabular view.

    Note: Since 5.5.0, the default CSS style for `null` has been removed. It is possible to manually set it by using a `<span>` with the CSS class `UICSSClasses.TEXT.VALUE_ND`.

    See Also:
      - `getMessageForSettingNull(UIResponseContext)`
      - `getMessageForSettingValue(UIResponseContext)`

  - ### addForNullInTable

    public void addForNullInTable(UIResponseContext aResponse)
    Deprecated.
    Adds HTML or DHTML content to the HTTP response, used to denote that the current value is not defined (`null`) in the cell of the table view in cases when the field is in read-only mode.

    Default implementation displays nothing (an empty cell).

    Since:
      5.2.3

  - ### addForPrint

    @Deprecated public void addForPrint(UIResponseContext aResponse)
    Deprecated.
    This method is no longer invoked.

  - ### addList

    public void addList(UIResponseContext aResponse)
    Deprecated.
    Overrides to add HTML or DHTML content to the HTTP response, so as to display or edit the current element's whole `List` within the record form. This method is invoked only if the current element is an aggregated list (that is, a element with `maxOccurs > 1`).

    The default implementation of this method is the following:

    - If the current element is a group, it invokes `addForDisplay(UIResponseContext)` or `addForEdit(UIResponseContext)` according to the rendering mode (backward compatibility).
    - Otherwise, if the current element is a field, it invokes the best matching component. In this case, this will invoke `addForDisplay(UIResponseContext)` or `addForEdit(UIResponseContext)` of this UI Bean for each occurrence.

    It is possible to manage input validation by implementing `shallValidateInputList(UIRequestContext)` or `validateInputList(UIRequestContext)`.

    Since:
      5.2.0
    See Also:
      - `UIContext.getPathForListOccurrence(int)`

  - ### getMessageForSettingNull

    public UserMessage getMessageForSettingNull(UIResponseContext aResponse)
    Deprecated.
    Returns the message to display in the user interface when setting the value of the associated element to `null` .

    Default implementation returns a standard message for this action.

  - ### getMessageForSettingValue

    public UserMessage getMessageForSettingValue(UIResponseContext aResponse)
    Deprecated.
    Returns the message to display in the user interface when editing a value of the associated element; the action is available when the current value is undefined (`null`) in the user interface.

    Default implementation returns a standard message for this action.

  - ### shallValidateInput

    public boolean shallValidateInput(UIRequestContext aRequest)
    Deprecated.
    Returns `true` if the user input associated with this editor will be validated; returns `false` if the local user input related to the current UI bean is ignored beyond the execution of this method.

    More precisely, user input validation is performed in five steps:

    1. This method is invoked and decides whether the remaining steps below are to be invoked (it can also itself perform validation tasks).
    2. If this method returns `true`: the container automatically validates the input associated with each "standard UI bean". A standard UI bean is one that has been added to this editor via one of the `UIResponseContext.addUI...()` methods.
    3. If this method returns `true`: the method `validateInput()` is invoked. It can, for example, perform user interface-specific checks.
    4. The constraints defined by data model nodes are executed, potentially adding their own error messages.
    5. Finally, if no errors block the submit, the updates done on the context are committed to the current dataspace. If there are errors, the page is redisplayed with the error messages.

    Default implementation always returns `true`.

    See Also:
      - `validateInput(UIRequestContext)`

  - ### shallValidateInputList

    public boolean shallValidateInputList(UIRequestContext aRequest)
    Deprecated.
    Same as `shallValidateInput` for an aggregated list.
    Since:
      5.2.0
    See Also:
      - `addList(UIResponseContext)`
      - `shallValidateInput(UIRequestContext)`

  - ### validateInput

    public void validateInput(UIRequestContext aRequest)
    Deprecated.
    Offers the opportunity to perform custom validation upon user input. It typically does so by retrieving the HTTP parameter values from the incoming request and checking them, so as to supply the validation context with new converted values. It can also add error messages.

    This method is only called if the method `shallValidateInput()` has returned `true`, and after the container has automatically validated the input associated with each UI bean that has been added via one of the `UIResponseContext.addUI...()` methods.

    Default implementation does nothing.

    See Also:
      - `shallValidateInput(UIRequestContext)`

  - ### validateInputList

    public void validateInputList(UIRequestContext aRequest)
    Deprecated.
    Does the same thing as `validateInput` for an aggregated list.

    If new elements in the list must be added, existing elements deleted, or if the order of elements must be changed, then a new list must be created, fed with elements possibly obtained from the context and finally the new list must be set to the context. The following example builds a list with 3 elements, with one element of each element set programmatically (other elements may have been set by built-in UI components), finally the list order is reversed:

         List newList = new ArrayList();
         for (int i = 0; i < 3; i++)
         {
                Path occurrencePath = aRequest.getPathForListOccurrence(i);
                String valueInform = aRequest
                        .getOptionalRequestParameterValue(aRequest.getWebNameForPath(occurrencePath.add(FIELD_X)));
                aRequest.getValueContext(occurrencePath.add(FIELD_X)).setNewValue(valueInform);
                MyBean occ = (MyBean) aRequest.getValue(occurrencePath);
                newList.add(occ);
         }
         Collections.reverse(newList);
         aRequest.getValueContext().setNewValue(newList);

    It is important to note that setting a new list on the validation context will imply that modifications in the sub-context will be ignored for the committed list, however these modifications remain accessible through direct access on the context (by means of a method such as `aContext.getValueContext(occurrencePath.add(FIELD_X))`).

    Since:
      5.2.0
    See Also:
      - `addList(UIResponseContext)`
      - `validateInput(UIRequestContext)`