Package com.orchestranetworks.ui

# Class UIAjaxComponent

java.lang.Object
com.orchestranetworks.ui.UIAjaxComponent

public abstract class UIAjaxComponent extends Object

Abstract class for implementing an Ajax component. A user interface service or a user interface editor (defined using a `UIBeanEditor`) can dynamically perform certain operations using an Ajax component.

### Use cases

An Ajax component may be used when dynamic operations must be performed inside a user interface service or a user interface editor.

If the Ajax component is used by a user interface editor, then it must be defined in the data model declaring the `UIBeanEditor`. If the Ajax component is used by a user interface service, then it must be either defined in the data model or the module declaring the service.

### Component Declaration

#### Declaring an Ajax component in a data model

The component must be declared as a global element in the data model, as follows:

>      <xs:complexType name="MyAjaxComponentName">
>             <xs:annotation>
>                     <xs:appinfo>
>                             <osd:ajaxComponent class="com.foo.MyAjaxComponent"/>
>                     </xs:appinfo>
>             </xs:annotation>
>      </xs:complexType>

Where `com.foo.MyAjaxComponent` is the fully qualified name of a class extending this class. The declaration may also use parameters:

>      <osd:ajaxComponent class="com.foo.MyAjaxComponent">
>             <param1>...</param1>
>             <param2>...</param2>
>      </osd:ajaxComponent>

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

For more information, see the JavaBean specification.

#### Declaring an Ajax component in a module

An Ajax component can also be used by a service defined in a module. The component must be declared in the `module.xml` file associated with the corresponding module.

The component is declared as follows:

>      <ajaxComponents>
>           <ajaxComponent name="MyAjaxComponentName" className="com.foo.MyAjaxComponent"/>
>      </ajaxComponents>

The element `ajaxComponents` must declare all Ajax components available to the services defined in this module.

`com.foo.MyAjaxComponent` is the fully qualified name of a class extending this class.

### Interactions between client and server

The client-server interaction process consists of the following steps:

1. Client side: calls an Ajax component on a user action in a user interface service or a user interface editor using `UIResourceLocator.getURLForAjaxComponent(String)`.
2. Server side: receives the Ajax call (HTTP request) and the specified class implementing this interface is instantiated through its default constructor. If there are the JavaBean property setters, they are called (in the example above, `setParam1(...)` and `setParam2(...)`).
3. Server side: the method `doAjaxResponse(UIAjaxContext)` is invoked on the instantiated object.
4. Server side: the response generated by the Ajax component is sent back to the calling user interface service or user interface editor.
5. Client side: receives the Ajax response and refreshes HTML according to the response.

### How-to

The use of an Ajax component implies correctly handling the HTTP request and HTTP response using JavaScript code.

To facilitate the use of Ajax components, EBX® provides the JavaScript prototype `EBX_AJAXResponseHandler` for sending the request and handling the response.

This prototype defines the method `sendRequest(urlToAjaxComponent)` for sending the Ajax request. The URL to the Ajax component can found by calling the method `UIResourceLocator.getURLForAjaxComponent(String)` (in the context of a `UIBeanEditor`, a `UIAjaxContext`, or a `ServiceContext`).

The following methods must be redefined and are mandatory in JavaScript classes that will use the `EBX_AJAXResponseHandler` prototype.

- `handleAjaxResponseSuccess(responseContent)`: this method defines the operations to perform if the Ajax response has been generated successfully. The parameter `responseContent` contains the plain-text response generated by this component.
- `handleAjaxResponseFailed(responseContent)`: this method defines the operations to perform if the Ajax response has failed, namely in case of a network error or server-side exception in `doAjaxResponse(UIAjaxContext)`. The parameter `responseContent` contains the plain-text response generated by this component.

The following JavaScript example shows how to use this prototype:

>      // Definition of the custom Ajax handler
>      MyAjaxHandler = function(anyParameters){
>          // Not mandatory, but for potential storage of parameters (eg. an id of an HTML element)
>          this.initialParameters = anyParameters;

>          // This method is mandatory
>          this.handleAjaxResponseSuccess = function(responseContent){
>             // Operations to perform if the Ajax response has been successfully generated.
>          };

>          // This method is mandatory
>          this.handleAjaxResponseFailed = function(responseContent){
>             // Operations to perform if the Ajax response has failed.
>          };
>      };

>      // Specifies that the custom Ajax handler uses the prototype provided by EBX®
>      MyAjaxHandler.prototype = new EBX_AJAXResponseHandler();

>      // Defines the function that sends the Ajax request.
>      // This function can be attached to a JavaScript event (i.e. onclick, onkeydown etc.).
>      function callAjaxComponent(anyParameters, anyRequestParameter){
>          // Initializes the custom Ajax handler
>          var myAjaxHandler = new MyAjaxHandler(anyParameters);

>          // Some parameters can be added to the request, then retrieved on the server side using UIAjaxContext.getOptionalRequestParameterValue(String)
>          var requestParameter = "&parameter=" + anyRequestParameter;

>          // Sends the request to the given Ajax component.
>          // The URL to the Ajax component is obtained calling UIResourceLocator.getURLForAjaxComponent(String)
>          myAjaxHandler.sendRequest(urlToAjaxComponent + requestParameter);
>      };

When the function `sendRequest(urlToAjaxComponent)` is called, the request is sent to the server and the method `doAjaxResponse(UIAjaxContext)` of the corresponding Ajax component is called. The server sends the response from the Ajax component to the client code, and the function `handleAjaxResponseSuccess` or `handleAjaxResponseFailed` will be automatically called to handle the response.

### IMPORTANT NOTES

1. It is strongly discouraged to perform updates in an Ajax component. If this is done, inconsistencies may occur in the calling user-defined service or user-defined editor. The dirty read mechanism must be considered when using Ajax components. That is, all updates that may be done in this component will not be visible in the caller component. Thus, Ajax components should only be used for handling dynamic requests in a read-only mode.
2. The plain-text response generated by this component is wrapped in custom XML content. It is thus strongly advised to use the provided JavaScript prototype for handling the response generated by the Ajax component.

### Error handling

If the method `doAjaxResponse(UIAjaxContext)` throws an `Exception`, the exception's message will be added to `kernel.log`. On the client side, the method `handleAjaxResponseFailed(responseContent)` will be invoked.

Error, warning and info messages can also be added to the client-side message box by calling `UIAjaxContext.addUserMessage(UserMessage)`.

### Multi-threading

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

Since:
  5.2.0
See Also:
  - `UIResourceLocator.getURLForAjaxComponent(String)`
  - UI Developer Guide

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UIAjaxComponent()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `doAjaxResponse(UIAjaxContext aResponse)`
  When the client sends an HTTP request targeting this component, this method is invoked.

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

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

- ## Constructor Details

  - ### UIAjaxComponent

    public UIAjaxComponent()

- ## Method Details

  - ### doAjaxResponse

    public abstract void doAjaxResponse(UIAjaxContext aResponse)
    When the client sends an HTTP request targeting this component, this method is invoked. The implementation must supply the Ajax response.
    See Also:
      - `UIBodyWriter.add(String)`