Package com.orchestranetworks.ui

# Interface UIAjaxContext

All Superinterfaces:
  `UIBodyWriter`, `UIComponentWriter`, `UIDependencyRegisterer`, `UIJavaScriptWriter`, `UIResourceLocator`, `UISessionContext`

public interface UIAjaxContext extends UIComponentWriter
Encapsulates an HTTP response so that an Ajax component is able to generate its part of the DHTML page.

### Extending `UIBodyWriter`

The methods `add(...)` and `add_cr(...)` write text into the body of the Ajax response output stream.

This text has no constraints (it can be a raw string, HTML, CSV, JSON, XML ...), provided that the JavaScript function `handleAjaxResponseSuccess(responseContent)` manages that kind of data format.

It is up to the caller to correctly handle the Ajax response generated by this component. So it is strongly advised to use the `EBX_AJAXResponseHandler` JavaScript prototype for handling the response.

### Extending `UIJavaScriptWriter`

The methods `addJS(...)` and `addJS_cr(...)` write a piece of JavaScript code into the Ajax response output stream.

The entire JavaScript code will be executed once the function `handleAjaxResponseSuccess(responseContent)` has been executed.

Since:
  5.2.0
See Also:
  - `UIAjaxComponent`
  - UI Developer Guide

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addUserMessage(UserMessage aMessage)`
  Add a user message to the message box according to its severity.
  `Adaptation`
  `getCurrentAdaptation()`
  Returns the dataset or record currently selected in the session.
  `Adaptation`
  `getCurrentDataSet()`
  Returns the dataset currently selected in the session.
  `SchemaNode`
  `getCurrentDataSetNode()`
  Returns the dataset node currently selected in the session.
  `AdaptationHome`
  `getCurrentHome()`
  Returns the dataspace or snapshot currently selected in the session.
  `Adaptation`
  `getCurrentRecord()`
  Returns the record currently selected in the session.
  `SchemaNode`
  `getCurrentRecordNode()`
  Returns the record node currently selected in the session.
  `HierarchyNode`
  `getHierarchyNode()`
  Returns the current hierarchy node if the user interface is in the context of a hierarchy.
  `String`
  `getOptionalRequestParameterValue(String aParameterName)`
  Returns the HTTP parameter value from the incoming request.
  `String[]`
  `getOptionalRequestParameterValues(String aParameterName)`
  Returns the HTTP parameter values from the incoming request.
  `ServiceContext`
  `getServiceContext()`
  Deprecated.
  From release 6.0, this API is no longer supported.
  `Object`
  `getValue(Path aPath)`
  Returns the value of the specified node.
  `boolean`
  `isCalledFromUIService()`
  Returns `true` if the Ajax component is called from a user service.

  ### Methods inherited from interface com.orchestranetworks.ui.UIBodyWriter

  `add, add, add, add_cr, add_cr, addSafeAttribute, addSafeAttribute, addSafeInnerHTML, addSafeInnerHTML`

  ### Methods inherited from interface com.orchestranetworks.ui.UIComponentWriter

  `addButtonHelp, addButtonJavaScript, addButtonJavaScriptToggle, addUILabel, addUserAvatar, buildButtonPreview, buildButtonPreview, buildButtonPreview, endBorder, endExpandCollapseBlock, endFormGroup, endFormRow, endTableFormRow, newExpandCollapseBlock, newFormGroup, newFormRow, startBorder, startBorder, startBorder, startExpandCollapseBlock, startExpandCollapseBlock, startFormGroup, startFormGroup, startFormRow, startFormRow, startFormRow, startFormRow, startTableFormRow`

  ### Methods inherited from interface com.orchestranetworks.ui.UIDependencyRegisterer

  `addJavaScriptDependency`

  ### Methods inherited from interface com.orchestranetworks.ui.UIJavaScriptWriter

  `addJS, addJS_addResizeWorkspaceListener, addJS_cr, addJS_cr, addJS_openPreviewImage, addJS_openPreviewImageFromVar, addJS_setButtonDisabled, addJS_setExpandCollapseBlockExpanded, addJS_setStateToToggleButton, addJS_switchToPerspective, addJS_switchToPerspectiveAction`

  ### Methods inherited from interface com.orchestranetworks.ui.UIResourceLocator

  `createWebComponentForRootSession, createWebComponentForSubSession, getURLForAjaxComponent, getURLForAjaxComponent, getURLForPerspectiveSelection, getURLForPerspectiveSelection, getURLForResource, getURLForResource, getURLForResource, getURLForResource, getURLForResource, getURLForRest, getURLForSelection, getURLForSelection, getURLForSelection, getURLForSelection, getURLForSelection, getURLForSelection, getURLForViewSelection`

  ### Methods inherited from interface com.orchestranetworks.ui.UISessionContext

  `getLocale, getSession`

- ## Method Details

  - ### addUserMessage

    void addUserMessage(UserMessage aMessage)
    Add a user message to the message box according to its severity.
    Since:
      5.3.1

  - ### isCalledFromUIService

    boolean isCalledFromUIService()

    Returns `true` if the Ajax component is called from a user service.

    It will always return `false` if called from a UI bean whether this UI bean is hosted or not by a user service.

  - ### getOptionalRequestParameterValue

    String getOptionalRequestParameterValue(String aParameterName)
    Returns the HTTP parameter value from the incoming request.

  - ### getOptionalRequestParameterValues

    String[] getOptionalRequestParameterValues(String aParameterName)
    Returns the HTTP parameter values from the incoming request.

  - ### getHierarchyNode

    HierarchyNode getHierarchyNode()
    Returns the current hierarchy node if the user interface is in the context of a hierarchy. Returns `null` otherwise.

  - ### getCurrentAdaptation

    Adaptation getCurrentAdaptation()
    Returns the dataset or record currently selected in the session.

    This method returns a dataset if the current Ajax component is called from:

    - a dataset node,
    - a service running on a dataset,
    - a service running on an entire table,
    - a service running on a table selection and more than one record is selected.

    This method returns a record if the current Ajax component is called from:

    - a record node,
    - a service running on a table selection and if a single record is selected,
    - a service running on a page record,
    - a service running on a hierarchy node.

    Returns `null` if this Ajax component is called in the context of a record creation or duplication.

    Throws:
      `IllegalStateException` - if the current Ajax component is called from a service on a dataspace or a snapshot.
    See Also:
      - `getCurrentDataSet()`
      - `getCurrentRecord()`

  - ### getCurrentDataSetNode

    SchemaNode getCurrentDataSetNode()
    Returns the dataset node currently selected in the session. Returns `null` if no dataset is selected.
    Since:
      5.3.1

  - ### getCurrentRecordNode

    SchemaNode getCurrentRecordNode()
    Returns the record node currently selected in the session. Returns `null` if no record is selected.
    Since:
      5.3.1

  - ### getCurrentRecord

    Adaptation getCurrentRecord()
    Returns the record currently selected in the session.

    Returns `null` if this Ajax component is called from:

    - a dataset node,
    - the context of a record creation or duplication,
    - a service running on a dataset,
    - a service running on a whole table,
    - a service running on a table selection with more than one record selected.
    Throws:
      `IllegalStateException` - if the current Ajax component is called from a service on a dataspace or on a snapshot.
    Since:
      5.2.2

  - ### getCurrentDataSet

    Adaptation getCurrentDataSet()
    Returns the dataset currently selected in the session.
    Throws:
      `IllegalStateException` - if the current Ajax component is called from a service on a dataspace or a snapshot.
    Since:
      5.2.2

  - ### getCurrentHome

    AdaptationHome getCurrentHome()
    Returns the dataspace or snapshot currently selected in the session.

  - ### getValue

    Object getValue(Path aPath)
    Returns the value of the specified node. Returns `null` if the value of the node is undefined.

    If this method is called on an `Adaptation`, a lookup mechanism is used to retrieve the value (see Inheritance and value resolution).

    ##### Access and mapping rules

    The access and mapping rules between XML Schema and Java are described in the chapter Mapping to Java.

    Parameters:
      `aPath` - required, resolved in the context of the current record, or the current dataset if the current record is null.
    Throws:
      `PathAccessException` -
  - if `aPath` does not refer to an existing node in the underlying type tree structure,
  - the specified node is above a terminal node.
  Since:
    5.5.0
  See Also:
    - `getCurrentRecord()`
    - `getCurrentDataSet()`

- ### getServiceContext

  @Deprecated ServiceContext getServiceContext()
  Deprecated.
  From release 6.0, this API is no longer supported. The new `UserService` API should be used instead.
  Returns an instance of `ServiceContext` if this AJAX component is called from a UIService, Returns null otherwise.
  Since:
    5.5.0
  See Also:
    - `isCalledFromUIService()`