Package com.orchestranetworks.userservice

# Interface UserServiceAjaxRequest

public interface UserServiceAjaxRequest
Interface that an Ajax request callback must implement.

### How-to

The use of an Ajax callback implies to correctly handle the HTTP request and the HTTP response using JavaScript code.

The plain-text response generated by the callback is wrapped by EBX® in specific XML content. Therefore, it is strongly advised to use the provided 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 callback can be generated by calling method `UserServiceResourceLocator.getURLForAjaxRequest(UserServiceAjaxRequest)`.

The following methods must be redefined and are mandatory in JavaScript code 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. 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 (e.g. 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 UserServiceRequest.getParameter(String)
>          var requestParameter = "&parameter=" + anyRequestParameter;

>          // Sends the request to the Ajax callback.
>          // The URL to the Ajax component is obtained calling UserServiceResourceLocator.getURLForAjaxRequest(UserServiceAjaxRequest)
>          myAjaxHandler.sendRequest(urlToAjaxComponent + requestParameter);
>      };

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

### Error handling

If the callback 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 `UserServiceAjaxResponse.addMessage(UserMessage)`.

Since:
  5.8.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `processRequest(UserServiceAjaxContext anAjaxContext, UserServiceAjaxResponse anAjaxResponse)`
  Processes the Ajax request and writes the response.

- ## Method Details

  - ### processRequest

    void processRequest(UserServiceAjaxContext anAjaxContext, UserServiceAjaxResponse anAjaxResponse)
    Processes the Ajax request and writes the response.
    Parameters:
      `anAjaxContext` - provides information on the request.
      `anAjaxResponse` - the object to use to generate the response.