Package com.orchestranetworks.ui

Class 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 Detail

      • UIAjaxComponent

        public UIAjaxComponent()

    • Method Detail

      • 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)