Package com.orchestranetworks.ui

# Class UIHttpManagerComponent

java.lang.Object
com.orchestranetworks.ui.UIHttpManagerComponent

public abstract class UIHttpManagerComponent extends Object
This class is a utility for invoking user interface components using the HTTP protocol.

A general introduction to EBX® as a Web Component is available here.

### How to obtain a Web Component

An instance of this class can be obtained with the following factory methods:

- The method `UIResourceLocator.createWebComponentForSubSession()` allows creating a sub-session that shares the current session's authentication and all of its properties.
- The method `UIResourceLocator.createWebComponentForRootSession()` allows creating a root session connected to the current application server instance and EBX® repository.
- The methods `createWithBaseURI` allow creating Web Components from an external application that does not have a session, or on another application server running EBX®.

With the second and third options, the URL that is obtained is a permanent link (permalink).

### User authentication

The authentication uses the first applicable case of the following:

1. If this component has been obtained by invoking the method `UIResourceLocator.createWebComponentForSubSession()`, the authentication is automatic and the new `Session` shares the properties of the calling session.
2. Otherwise, if the parameters `login` and `password` are specified (see method `setUserLoginPassword(String, String)`), the method `Directory.authenticateUserFromLoginPassword(String, String)` is called when the HTTP request is received by the application server. If the user cannot be authenticated using the specified credentials, an 'access denied' page is returned.
3. Otherwise, the method `Directory.authenticateUserFromHttpRequest(HttpServletRequest)` is called (it is up to the specific directory to implement this method).
   1. If the method throws an exception, an 'access denied' page is returned.
   2. If the method returns `null` (default implementation), the request is considered to have no authentication specified, so the login/password page is returned to the user. When this page is submitted, the method `Directory.authenticateUserFromLoginPassword(String, String)` is called.

See Also:
  - Manager Components Reference
  - `UIResourceLocator`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `UIHttpManagerComponent.CloseButtonSpec`
  Defines the appearance of the close button.
  `static final class`
  `UIHttpManagerComponent.DataSetFeatures`
  Constants for features available in dataset.
  `static final class`
  `UIHttpManagerComponent.RecordFeatures`
  Constants for features available in record form.
  `static final class`
  `UIHttpManagerComponent.Scope`
  Defines the scope of the user navigation, namely, the parts of the user interface that are available to the user during the session.
  `static final class`
  `UIHttpManagerComponent.ViewFeatures`
  Constants for features available in tables and hierarchies.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `compareSelectionWithEntity(HomeKey homeOnRightKey, AdaptationName instanceOnRight, String tableOrOccurrenceOnRight)`
  Specifies the activation of the `comparison service`.
  `static UIHttpManagerComponent`
  `createOnAjaxContext(UIAjaxContext aContext)`
  Deprecated.
  This method has been replaced by `UIResourceLocator.createWebComponentForSubSession()`.
  `static UIHttpManagerComponent`
  `createOnServiceContext(ServiceContext aContext)`
  Deprecated.
  This method has been replaced by `UIResourceLocator.createWebComponentForSubSession()`.
  `static UIHttpManagerComponent`
  `createOnUIBeanContext(UIResponseContext aContext)`
  Deprecated.
  This method has been replaced by `UIResourceLocator.createWebComponentForSubSession()`.
  `static UIHttpManagerComponent`
  `createOnUILabelRendererForHierarchyContext(UILabelRendererForHierarchyContext aContext)`
  Deprecated.
  This method has been replaced by `UIResourceLocator.createWebComponentForSubSession()`.
  `static UIHttpManagerComponent`
  `createWithBaseURI(String baseURI)`
  Creates an instance of this class in order to call the EBX® user interface from an external application.
  `static UIHttpManagerComponent`
  `createWithBaseURI(String baseURI, boolean enforceStrongEncoding)`
  Deprecated.
  Since 5.9.0, use instead `createWithBaseURI(String)`.
  `static UIHttpManagerComponent`
  `createWithBaseURI(String baseURI, boolean enforceStrongEncoding, AdaptationName aManagerReference)`
  Deprecated.
  Since 5.9.0, use instead `createWithBaseURI(String, AdaptationName)`.
  `static UIHttpManagerComponent`
  `createWithBaseURI(String baseURI, AdaptationName aManagerReference)`
  Creates an instance of this class in order to call the EBX® user interface from an external application.
  `static UIHttpManagerComponent`
  `createWithURIWithParameters(String uriWithParameters)`
  Creates an instance of this class in order to call the EBX® user interface from an external application.
  `static UIHttpManagerComponent`
  `createWithURIWithParametersForSubSession(String uriWithParameters, Session aSession)`
  Creates an instance of this class in order to call the EBX® user interface in a separate sub-session (namely, a Web Component).
  `Map<String,String>`
  `getAdditionalParameters()`
  Returns all additional parameters.
  `String`
  `getAdditionalParameterValue(String aParameterName)`
  Returns the requested additional parameter or `null` if this parameter is not defined.
  `UIHttpManagerComponent.CloseButtonSpec`
  `getCloseButtonSpec()`
  Returns the close button display style for this Web Component.
  `CompareFilter`
  `getCompareFilter()`
  Returns the comparison filter defined for this Web Component.
  `HomeKey`
  `getHomeKey()`
  `HomeKey`
  `getHomeKeyToCompareWith()`
  `List<String>`
  `getHttpParameterNames()`
  Returns the names of the HTTP parameters that are specified by this instance.
  `String`
  `getHttpParameterValue(String aParameterName)`
  Returns the String value of a parameter, returns `null` if the parameter is not defined.
  `AdaptationReference`
  `getInstanceReference()`
  `AdaptationReference`
  `getInstanceReferenceToCompareWith()`
  `Locale`
  `getLocale()`
  Returns the locale specified for the new user session, returns `null` if no specific locale has been set.
  `final String`
  `getPerspectiveName()`
  Returns the selected perspective name.
  `String`
  `getRedirectionURI()`
  Returns the URI that will be used to redirect the user after closing a session of EBX® user interface.
  `UIHttpManagerComponent.Scope`
  `getScope()`
  Returns the scope defined for this Web Component.
  `ServiceKey`
  `getService()`
  Returns the service to be activated, `null` if no specific service has been set.
  `String`
  `getTrackingInfo()`
  Returns tracking info for the new user session, returns `null` if no specific tracking info has been set.
  `abstract String`
  `getURIWithoutParameters()`
  This function returns the URI to EBX® user interface, without specific parameters.
  `String`
  `getURIWithParameters()`
  This function returns the URI to EBX® user interface, including the parameters specified by this instance.
  `String`
  `getURIWithParameters(String aBaseURI)`
  `String`
  `getUserLogin()`
  Returns the user login, `null` if no login/password is specified.
  `String`
  `getUserPassword()`
  Returns the user password, `null` if no login/password is specified.
  `String`
  `getViewPublication()`
  Returns the published custom view that will be applied to the selected content.
  `WorkflowView`
  `getWorkflowView()`
  Returns the workflow view using the service `ServiceKey.WORKFLOW`.
  `String`
  `getXPathString()`
  `String`
  `getXPathStringToCompareWith()`
  `void`
  `hideAllDataSetFeatures()`
  If called, all dataset features will be hidden.
  `void`
  `hideAllRecordFeatures()`
  If called, all record features will be hidden.
  `void`
  `hideAllViewFeatures()`
  If called, all table or hierarchy features will be hidden.
  `void`
  `hideDataSetFeature(String aFeature)`
  If called, all dataset features will be displayed except the one specified.
  `void`
  `hideDataSetFeatures(List<String> aFeaturesListToHide)`
  If called, all dataset features will be displayed except those specified by the given list.
  `void`
  `hideRecordFeature(String aFeature)`
  If called, all record features will be displayed except the one specified.
  `void`
  `hideRecordFeatures(List<String> aFeaturesListToHide)`
  If called, all record features will be displayed except those specified by the given list.
  `void`
  `hideViewFeature(String aFeature)`
  If called, all table or hierarchy features will be displayed except the one specified.
  `void`
  `hideViewFeatures(List<String> aFeaturesListToHide)`
  If called, all table or hierarchy features will be displayed except those specified by the given list.
  `final void`
  `initFromHttpRequest(HttpServletRequest request)`
  Initializes this instance with the specified incoming request.
  `void`
  `select(HomeKey aDataSpaceOrSnapshotKey, AdaptationName aDataSetReference, Path aPath)`
  Selects the node in the specified dataset.
  `void`
  `select(HomeKey aDataSpaceOrSnapshotKey, AdaptationName aDataSetReference, String aXPathExpression)`
  Specifies an entity selection in the EBX® repository.
  `void`
  `selectHome(AdaptationHome aDataSpaceOrSnapshot)`
  Selects the specified dataspace or snapshot.
  `void`
  `selectHome(HomeKey aDataSpaceOrSnapshotKey)`
  Selects the specified dataspace or snapshot.
  `void`
  `selectInstance(HomeKey aDataSpaceOrSnapshotKey, AdaptationName aDataSetReference)`
  Selects the specified dataset.
  `void`
  `selectInstanceOrOccurrence(Adaptation aDataSetOrRecord)`
  Selects the specified dataset or record.
  `void`
  `selectInstanceOrOccurrenceWithPredicate(Adaptation aDataSetOrRecord, String aPredicate)`
  Selects the specified dataset or record with the specified predicate restriction.
  `void`
  `selectNode(Adaptation aDataSetOrRecord, Path aNode)`
  Selects the specified node.
  `void`
  `selectNode(Adaptation aDataSetOrRecord, Path aNode, String aPredicate)`
  Selects the specified node with the specified predicate restriction.
  `final void`
  `selectPerspective(String aPerspectiveName)`
  Selects the specified perspective.
  `final void`
  `selectPerspectiveAction(String aPerspectiveName, String aPerspectiveActionName)`
  Selects the specified perspective action.
  `final void`
  `selectWorkflowView(WorkflowView aWorkflowView)`
  Selects the specified workflow view using the service `ServiceKey.WORKFLOW`.
  `final void`
  `selectWorkItem(boolean shouldTakeAndStart, WorkItemKey aWorkItemKey)`
  Selects the specified work item using the service `ServiceKey.WORKFLOW`.
  `final void`
  `selectWorkItemInMonitoring(WorkItemKey aWorkItemKey)`
  Selects the specified work item using the service `ServiceKey.WORKFLOW` and in the workflow view `WorkflowView.MONITORING_WORKITEMS`
  `void`
  `setAdditionalParameter(String aParameterName, String aValue)`
  Adds an additional parameter.
  `void`
  `setAdditionalParameters(Map<String,String> aParameterMap)`
  Adds additional parameters.
  `void`
  `setCloseButtonSpec(UIHttpManagerComponent.CloseButtonSpec closeButtonSpec)`
  Specifies whether the close button is displayed for this Web Component, and if so, its display style.
  `void`
  `setCompareFilter(CompareFilter compareFilter)`
  Specifies the comparator filter for this Web Component.
  `final void`
  `setFirstCallDisplay(FirstCallDisplay aFirstCallDisplay)`
  Specifies what must be displayed upon first call, either the whole tabular or hierarchical or a record.
  `final void`
  `setFirstCallDisplayHierarchyExpanded()`
  Specifies that the hierarchy must be displayed expanded.
  `final void`
  `setFirstCallDisplayRecord(String aFirstCallDisplayPredicate)`
  Specifies that a record must be displayed upon first call.
  `void`
  `setLocale(Locale locale)`
  Specifies the locale for the new user session.
  `void`
  `setPageSize(int aPageSize)`
  Sets the number of rows that will be displayed per page.
  `void`
  `setPredicate(String aPredicate)`
  Sets a predicate to be applied to the selected table.
  `void`
  `setRedirectionURI(String redirectionUrl)`
  Specifies the URI that will be used to redirect the user after closing an EBX® user interface session.
  `void`
  `setScope(UIHttpManagerComponent.Scope scope)`
  Specifies the scope for this Web Component.
  `void`
  `setService(ServiceKey aServiceKey)`
  Specifies the service to be activated.
  `void`
  `setTrackingInfo(String trackingInfo)`
  Specifies tracking info for the new user session.
  `void`
  `setUserLoginPassword(String userLogin, String userPassword)`
  Specifies the login and password with which to authenticate the user.
  `void`
  `setViewPublication(String aPublication)`
  Specifies the published custom view that will be applied to the selected content.
  `void`
  `showAllDataSetFeatures()`
  If called, all dataset features will be displayed.
  `void`
  `showAllRecordFeatures()`
  If called, all record features will be displayed.
  `void`
  `showAllViewFeatures()`
  If called, all table or hierarchy features will be displayed.
  `void`
  `showDataSetFeature(String aFeature)`
  If called, all dataset features will be hidden except the one specified.
  `void`
  `showDataSetFeatures(List<String> aFeaturesListToDisplay)`
  If called, all dataset features will be hidden except those specified by the given list.
  `void`
  `showRecordFeature(String aFeature)`
  If called, all record features will be hidden except the one specified.
  `void`
  `showRecordFeatures(List<String> aFeaturesListToDisplay)`
  If called, all record features will be hidden except those specified by the given list.
  `void`
  `showViewFeature(String aFeature)`
  If called, all table or hierarchy features will be hidden except the one specified.
  `void`
  `showViewFeatures(List<String> aFeaturesListToDisplay)`
  If called, all table or hierarchy features will be hidden except those specified by the given list.

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

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

- ## Method Details

  - ### createWithURIWithParameters

    public static UIHttpManagerComponent createWithURIWithParameters(String uriWithParameters)
    Creates an instance of this class in order to call the EBX® user interface from an external application. A URI to EBX® user interface with parameters can be specified.
    Parameters:
      `uriWithParameters` - URI with parameters to EBX® web application.
    Since:
      6.0.0

  - ### createWithBaseURI

    public static UIHttpManagerComponent createWithBaseURI(String baseURI)
    Creates an instance of this class in order to call the EBX® user interface from an external application.
    Parameters:
      `baseURI` - Base URI to EBX® web application.
    See Also:
      - `createWithBaseURI(String, AdaptationName)`

  - ### createWithBaseURI

    @Deprecated public static UIHttpManagerComponent createWithBaseURI(String baseURI, boolean enforceStrongEncoding)
    Deprecated.
    Since 5.9.0, use instead `createWithBaseURI(String)`.
    Creates an instance of this class in order to call the EBX® user interface from an external application.
    Parameters:
      `baseURI` - Base URI to EBX® web application.
      `enforceStrongEncoding` - This parameter is now ignored.

  - ### createWithBaseURI

    public static UIHttpManagerComponent createWithBaseURI(String baseURI, AdaptationName aManagerReference)
    Creates an instance of this class in order to call the EBX® user interface from an external application.

    The default deployment requires a URL base of the following form:

    > `http://<host>[:<port>]/ebx/`

    Or, if the Java application is running on the same application server:

    > `/ebx/`

    Note: The URI base must refer to the servlet named `com.onwbp.front.FrontServlet` defined in the web application `ebx.war` (see file `/WEB-INF/web.xml` in `ebx.war`).

    Parameters:
      `baseURI` - Base URI to EBX® web application (see examples above).
      `aManagerReference` - Identifier of the EBX® user interface dataset (for example, `ebx-manager`).

  - ### createWithBaseURI

    @Deprecated public static UIHttpManagerComponent createWithBaseURI(String baseURI, boolean enforceStrongEncoding, AdaptationName aManagerReference)
    Deprecated.
    Since 5.9.0, use instead `createWithBaseURI(String, AdaptationName)`.
    Creates an instance of this class in order to call the EBX® user interface from an external application.

    The default deployment requires a URL base of the following form:

    > `http://<host>[:<port>]/ebx/`

    Or, if the Java application is running on the same application server:

    > `/ebx/`

    Note: The URI base must refer to the servlet named `com.onwbp.front.FrontServlet` defined in the web application `ebx.war` (see file `/WEB-INF/web.xml` in `ebx.war`).

    Parameters:
      `baseURI` - Base URI to EBX® web application (see examples above).
      `enforceStrongEncoding` - This parameter is now ignored.
      `aManagerReference` - Identifier of the EBX® user interface dataset (for example, `ebx-manager`).

  - ### createWithURIWithParametersForSubSession

    public static UIHttpManagerComponent createWithURIWithParametersForSubSession(String uriWithParameters, Session aSession)
    Creates an instance of this class in order to call the EBX® user interface in a separate sub-session (namely, a Web Component). As this uses a sub-session, the URL obtained by this type of component is not a permanent link (permalink). It is automatically authenticated and inherits all its properties from its parent session, except `trackingInfo` (these inherited properties are available using the `Session` interface).

    The Web Component must be invoked within a pop-up, inner pop-up, or iFrame. A standard inner pop-up can be created by using the method `UIComponentWriter.buildButtonPreview(String)`.

    A URI to EBX® user interface, including parameters for this instance, can be specified.

    Parameters:
      `uriWithParameters` - URI with parameters to EBX® web application.
      `aSession` - Current user session in EBX® user interface.
    Since:
      6.0.0
    See Also:
      - `UIResourceLocator.createWebComponentForSubSession()`

  - ### createOnServiceContext

    @Deprecated public static UIHttpManagerComponent createOnServiceContext(ServiceContext aContext)
    Deprecated.
    This method has been replaced by `UIResourceLocator.createWebComponentForSubSession()`.

  - ### createOnAjaxContext

    @Deprecated public static UIHttpManagerComponent createOnAjaxContext(UIAjaxContext aContext)
    Deprecated.
    This method has been replaced by `UIResourceLocator.createWebComponentForSubSession()`.

  - ### createOnUIBeanContext

    @Deprecated public static UIHttpManagerComponent createOnUIBeanContext(UIResponseContext aContext)
    Deprecated.
    This method has been replaced by `UIResourceLocator.createWebComponentForSubSession()`.

  - ### createOnUILabelRendererForHierarchyContext

    @Deprecated public static UIHttpManagerComponent createOnUILabelRendererForHierarchyContext(UILabelRendererForHierarchyContext aContext)
    Deprecated.
    This method has been replaced by `UIResourceLocator.createWebComponentForSubSession()`.

  - ### getURIWithoutParameters

    public abstract String getURIWithoutParameters()
    This function returns the URI to EBX® user interface, without specific parameters.
    See Also:
      - `getURIWithParameters()`
      - `getHttpParameterNames()`
      - `getHttpParameterValue(String)`

  - ### getURIWithParameters

    public String getURIWithParameters(String aBaseURI)

  - ### getURIWithParameters

    public String getURIWithParameters()
    This function returns the URI to EBX® user interface, including the parameters specified by this instance.

    Note: This method may return a String whose length is not supported by the browser or the Servlet Container.

    User authentication parameters have to be added according to the current user directory implementation.

    See Also:
      - `Directory.authenticateUserFromHttpRequest(HttpServletRequest)`

  - ### getHttpParameterNames

    public List<String> getHttpParameterNames()
    Returns the names of the HTTP parameters that are specified by this instance.

    Since the method `getURIWithParameters()` may give a URI that is too long, this method can be used for building a POST request.

    See Also:
      - `getHttpParameterValue(String)`

  - ### getHttpParameterValue

    public String getHttpParameterValue(String aParameterName)
    Returns the String value of a parameter, returns `null` if the parameter is not defined.

    See Also:
      - `getHttpParameterNames()`

  - ### initFromHttpRequest

    public final void initFromHttpRequest(HttpServletRequest request) throws IllegalArgumentException
    Initializes this instance with the specified incoming request.

    This method can be used to "forward" EBX® Web Component parameters to another page to perform the actual call.

    Throws:
      `IllegalArgumentException`

  - ### getUserLogin

    public String getUserLogin()
    Returns the user login, `null` if no login/password is specified.
    See Also:
      - `setUserLoginPassword(String, String)`

  - ### getUserPassword

    public String getUserPassword()
    Returns the user password, `null` if no login/password is specified.
    See Also:
      - `setUserLoginPassword(String, String)`

  - ### setUserLoginPassword

    public void setUserLoginPassword(String userLogin, String userPassword)
    Specifies the login and password with which to authenticate the user.

    The authentication process is detailed in this class comment.

  - ### getHomeKey

    public HomeKey getHomeKey()

  - ### getInstanceReference

    public AdaptationReference getInstanceReference()

  - ### getXPathString

    public String getXPathString()

  - ### selectHome

    public void selectHome(HomeKey aDataSpaceOrSnapshotKey)
    Selects the specified dataspace or snapshot.
    Throws:
      `IllegalArgumentException` - if `aDataSpaceOrSnapshotKey` is `null`.

  - ### selectInstance

    public void selectInstance(HomeKey aDataSpaceOrSnapshotKey, AdaptationName aDataSetReference)
    Selects the specified dataset.
    Throws:
      `IllegalArgumentException` - if `aDataSpaceOrSnapshotKey` is `null` or `aDataSetReference` is `null`.

  - ### select

    public void select(HomeKey aDataSpaceOrSnapshotKey, AdaptationName aDataSetReference, Path aPath)
    Selects the node in the specified dataset.
    Throws:
      `IllegalArgumentException` - if `aDataSpaceOrSnapshotKey` is `null`.
      `IllegalArgumentException` - if `xpath` is a relative path.

  - ### select

    public void select(HomeKey aDataSpaceOrSnapshotKey, AdaptationName aDataSetReference, String aXPathExpression) throws IllegalArgumentException
    Specifies an entity selection in the EBX® repository.

    This is the most general method of performing an entity selection.

    Parameters:
      `aDataSpaceOrSnapshotKey` - identifies a dataspace or a snapshot in the repository.
      `aDataSetReference` - identifies a dataset in the dataspace or snapshot. If `null`, this method is the same as `selectHome(HomeKey)`.
      `aXPathExpression` - XPath expression specifying a selection in the dataset. If `null` and dataset not `null`, this method is the same as `selectInstance(HomeKey, AdaptationName)`; if not `null` and the XPath expression specifies a predicate, this parameter overrides the method `setPredicate`.
    Throws:
      `IllegalArgumentException` - if `aDataSpaceOrSnapshotKey` is `null`, or `aDataSetReference` is `null` but not `aXPathExpression`.
      `IllegalArgumentException` - if `aXPathExpression` contains a relative path to the dataset node.
    See Also:
      - `setPredicate(String)`

  - ### selectHome

    public void selectHome(AdaptationHome aDataSpaceOrSnapshot)
    Selects the specified dataspace or snapshot.
    Throws:
      `IllegalArgumentException` - if `aDataSpaceOrSnapshot` is `null`.
    See Also:
      - `UIResourceLocator.getURLForSelection(AdaptationHome)`
      - `UIResourceLocator.getURLForSelection(AdaptationHome)`

  - ### selectInstanceOrOccurrence

    public void selectInstanceOrOccurrence(Adaptation aDataSetOrRecord)
    Selects the specified dataset or record.
    Throws:
      `IllegalArgumentException` - if `aDataSetOrRecord` is `null`.
    See Also:
      - `UIResourceLocator.getURLForSelection(Adaptation)`
      - `UIResourceLocator.getURLForSelection(Adaptation)`

  - ### selectInstanceOrOccurrenceWithPredicate

    public void selectInstanceOrOccurrenceWithPredicate(Adaptation aDataSetOrRecord, String aPredicate)
    Selects the specified dataset or record with the specified predicate restriction.
    Parameters:
      `aPredicate` - the predicate that defines the selection; if not `null`, this parameter overrides the method `setPredicate`.
    Throws:
      `IllegalArgumentException` - if `aDataSetOrRecord` is `null`.
    See Also:
      - XPath supported syntax.
      - `setPredicate(String)`

  - ### selectNode

    public void selectNode(Adaptation aDataSetOrRecord, Path aNode)
    Selects the specified node.
    Parameters:
      `aDataSetOrRecord` - a dataset or a record.
      `aNode` - a path to a node in the dataset; if `null` this method is the same as `selectInstanceOrOccurrence(Adaptation)`.
    Throws:
      `IllegalArgumentException` - if `aDataSetOrRecord` is `null`.
      `IllegalArgumentException` - if `aNode` is a relative path and `aDataSetOrRecord` is a dataset.
    See Also:
      - `UIResourceLocator.getURLForSelection(Adaptation, Path)`
      - `UIResourceLocator.getURLForSelection(Adaptation, Path)`

  - ### selectNode

    public void selectNode(Adaptation aDataSetOrRecord, Path aNode, String aPredicate)
    Selects the specified node with the specified predicate restriction.
    Parameters:
      `aDataSetOrRecord` - a dataset or a record.
      `aNode` - a path to a node in the dataset; if `null` this method is the same as `selectInstanceOrOccurrence(Adaptation)`.
      `aPredicate` - the predicate that defines the selection; if not `null`, this parameter overrides the method `setPredicate`.
    Throws:
      `IllegalArgumentException` - if `aDataSetOrRecord` is `null`.
      `IllegalArgumentException` - if `aNode` is a relative path and `aDataSetOrRecord` is a dataset.
    See Also:
      - XPath supported syntax.
      - `setPredicate(String)`

  - ### selectWorkflowView

    public final void selectWorkflowView(WorkflowView aWorkflowView)
    Selects the specified workflow view using the service `ServiceKey.WORKFLOW`.

    Note: The method `setService(ServiceKey)` will override parameters that have been automatically set by this method.

    Parameters:
      `aWorkflowView` - the key of the workflow view to select.
    Since:
      5.4.3

  - ### selectPerspective

    public final void selectPerspective(String aPerspectiveName)
    Selects the specified perspective.
    Parameters:
      `aPerspectiveName` - the name of the perspective to select.
    Since:
      5.9.0 fix B

  - ### selectPerspectiveAction

    public final void selectPerspectiveAction(String aPerspectiveName, String aPerspectiveActionName)
    Selects the specified perspective action.
    Parameters:
      `aPerspectiveName` - the name of the perspective to select.
      `aPerspectiveActionName` - the name of the perspective action to select.
    Since:
      5.9.0 fix B

  - ### setFirstCallDisplay

    public final void setFirstCallDisplay(FirstCallDisplay aFirstCallDisplay)
    Specifies what must be displayed upon first call, either the whole tabular or hierarchical or a record.
    Since:
      5.6.1

  - ### setFirstCallDisplayRecord

    public final void setFirstCallDisplayRecord(String aFirstCallDisplayPredicate)
    Specifies that a record must be displayed upon first call. If the specified predicate is not empty, the corresponding record will be opened. Otherwise, opens the first record in the request.
    Since:
      5.7.1
    See Also:
      - `FirstCallDisplay.record`

  - ### setFirstCallDisplayHierarchyExpanded

    public final void setFirstCallDisplayHierarchyExpanded()
    Specifies that the hierarchy must be displayed expanded. If a predicate is specified on the target table, the hierarchy will be expanded up to the nodes that match the predicate (see `select(HomeKey, AdaptationName, String)`).
    Since:
      5.8.0 fix D
    See Also:
      - `FirstCallDisplay.view`

  - ### selectWorkItem

    public final void selectWorkItem(boolean shouldTakeAndStart, WorkItemKey aWorkItemKey)
    Selects the specified work item using the service `ServiceKey.WORKFLOW`.

    Note: The methods `setPredicate(String)` and `setService(ServiceKey)` will override parameters that have been automatically set by this method.

    Parameters:
      `shouldTakeAndStart` - if `true`, the target work item will be automatically allocated to and started for the current user; does nothing if this is already the case.
      `aWorkItemKey` - the key of the work item to select.
    Throws:
      `IllegalArgumentException` - if `aWorkItemKey` is `null`.
    Since:
      5.4.3
    See Also:
      - `selectWorkItemInMonitoring(WorkItemKey)`

  - ### selectWorkItemInMonitoring

    public final void selectWorkItemInMonitoring(WorkItemKey aWorkItemKey)
    Selects the specified work item using the service `ServiceKey.WORKFLOW` and in the workflow view `WorkflowView.MONITORING_WORKITEMS`

    Note: The methods `setPredicate(String)` and `setService(ServiceKey)` will override parameters that have been automatically set by this method.

    Parameters:
      `aWorkItemKey` - the key of the work item to select
    Throws:
      `IllegalArgumentException` - if `aWorkItemKey` is `null`.
    Since:
      5.4.3
    See Also:
      - `selectWorkItem(boolean, WorkItemKey)`

  - ### getService

    public ServiceKey getService()
    Returns the service to be activated, `null` if no specific service has been set.

  - ### setService

    public void setService(ServiceKey aServiceKey)
    Specifies the service to be activated.

    If no service is defined, the entity specified using the `select...` methods is selected.

    If a service is specified, it may require the selection of some entities (and additional parameters for specific services). Built-in services are documented in the class `ServiceKey`) and specific services are documented in their own declarations.

    Parameters:
      `aServiceKey` - The service that must be activated when the EBX® Web Component is called, `null` if no specific service is activated.

  - ### getCompareFilter

    public CompareFilter getCompareFilter()
    Returns the comparison filter defined for this Web Component.
    Since:
      5.4.2

  - ### setCompareFilter

    public void setCompareFilter(CompareFilter compareFilter)
    Specifies the comparator filter for this Web Component.

    This property is interpreted only if the service `ServiceKey.COMPARE` is set.

    Since:
      5.4.2

  - ### getScope

    public UIHttpManagerComponent.Scope getScope()
    Returns the scope defined for this Web Component.
    Since:
      5.2.2

  - ### setScope

    public void setScope(UIHttpManagerComponent.Scope scope)
    Specifies the scope for this Web Component.

    If unspecified, a minimal scope will be applied and the user will only be able to work with the selected content.

    Since:
      5.2.2

  - ### getCloseButtonSpec

    public UIHttpManagerComponent.CloseButtonSpec getCloseButtonSpec()
    Returns the close button display style for this Web Component.
    Since:
      5.2.2

  - ### setCloseButtonSpec

    public void setCloseButtonSpec(UIHttpManagerComponent.CloseButtonSpec closeButtonSpec)
    Specifies whether the close button is displayed for this Web Component, and if so, its display style.

    If unspecified, the default is to display the logout button if the web component scope is full. Otherwise, no button is displayed.

    Since:
      5.2.2
    See Also:
      - `ServiceContext.getURLForEndingServiceInPopup()`

  - ### getRedirectionURI

    public String getRedirectionURI()
    Returns the URI that will be used to redirect the user after closing a session of EBX® user interface.

  - ### setRedirectionURI

    public void setRedirectionURI(String redirectionUrl)
    Specifies the URI that will be used to redirect the user after closing an EBX® user interface session.

    The URI can have an additional HTTP parameter that specifies a return code. The application that receives the URI can extract it by means of method `UIHttpManagerComponentHelper.getReturnCodeFromHttpRequest(jakarta.servlet.ServletRequest)`.

    See Also:
      - `UIHttpManagerComponentReturnCode`
      - redirect

  - ### getTrackingInfo

    public String getTrackingInfo()
    Returns tracking info for the new user session, returns `null` if no specific tracking info has been set.
    See Also:
      - `Session.getTrackingInfo()`

  - ### setTrackingInfo

    public void setTrackingInfo(String trackingInfo)
    Specifies tracking info for the new user session.
    See Also:
      - `Session.getTrackingInfo()`

  - ### getLocale

    public Locale getLocale()
    Returns the locale specified for the new user session, returns `null` if no specific locale has been set.
    See Also:
      - `Session.getLocale()`

  - ### setLocale

    public void setLocale(Locale locale)
    Specifies the locale for the new user session.
    See Also:
      - `Session.getLocale()`

  - ### compareSelectionWithEntity

    public void compareSelectionWithEntity(HomeKey homeOnRightKey, AdaptationName instanceOnRight, String tableOrOccurrenceOnRight)
    Specifies the activation of the `comparison service`.

    The user is directed to the comparison interface:

    - The selected entity, specified by one of the `select...` methods, is displayed on the left side.
    - The entity that is specified by the arguments of this method is displayed on the right side..

    Entities that can be compared are: two dataspaces or versions, two datasets, two tables, or two table records.

    Parameters:
      `homeOnRightKey` - identifies a dataspace or a snapshot in the repository.
      `instanceOnRight` - identifies a dataset in the specified dataspace or snapshot, `null` if comparing homes. The reference to a dataset is obtained by invoking the method `Adaptation.getAdaptationName()`.
      `tableOrOccurrenceOnRight` - XPath expression that specifies either a unique table record in the specified dataset, or a table, or `null` if comparing dat sets or homes. The XPath expression that uniquely identifies a unique table record is directly obtained by invoking the method `Adaptation.toXPathExpression()`.
    See Also:
      - `select(HomeKey, AdaptationName, String)`

  - ### getHomeKeyToCompareWith

    public HomeKey getHomeKeyToCompareWith()
    See Also:
      - `compareSelectionWithEntity(HomeKey, AdaptationName, String)`

  - ### getInstanceReferenceToCompareWith

    public AdaptationReference getInstanceReferenceToCompareWith()
    See Also:
      - `compareSelectionWithEntity(HomeKey, AdaptationName, String)`

  - ### getXPathStringToCompareWith

    public String getXPathStringToCompareWith()
    See Also:
      - `compareSelectionWithEntity(HomeKey, AdaptationName, String)`

  - ### getViewPublication

    public String getViewPublication()
    Returns the published custom view that will be applied to the selected content.
    Since:
      6.0.0
    See Also:
      - `setViewPublication(String)`

  - ### setViewPublication

    public void setViewPublication(String aPublication)
    Specifies the published custom view that will be applied to the selected content.

    The predicate specified by the custom view will be combined with the `local predicate`, if specified, as a logical 'AND' operation.

    Parameters:
      `aPublication` - the unique publication name of the custom view to be applied.
    Since:
      5.2.3
    See Also:
      - Technical reference

  - ### setPredicate

    public void setPredicate(String aPredicate)
    Sets a predicate to be applied to the selected table. If no table is selected, this predicate will be ignored.

    The predicate can also be set using methods such as `selectNode`.

    Parameters:
      `aPredicate` - the predicate to apply as a filter.
    Since:
      5.4.3
    See Also:
      - `setViewPublication(String)`
      - `XPathExpressionHelper.getPredicateForXPath(String)`

  - ### getAdditionalParameterValue

    public String getAdditionalParameterValue(String aParameterName)
    Returns the requested additional parameter or `null` if this parameter is not defined.
    Throws:
      `IllegalArgumentException` - if the parameter name is null or reserved.
    Since:
      5.9.0
    See Also:
      - `setAdditionalParameter(String, String)`

  - ### setAdditionalParameter

    public void setAdditionalParameter(String aParameterName, String aValue)
    Adds an additional parameter.
    Throws:
      `IllegalArgumentException` - if the parameter name is null or reserved.
    Since:
      5.9.0
    See Also:
      - `Session.getInputParameterValue(boolean, String)`

  - ### getAdditionalParameters

    public Map<String,String> getAdditionalParameters()
    Returns all additional parameters.
    Since:
      5.9.0
    See Also:
      - `setAdditionalParameter(String, String)`

  - ### setAdditionalParameters

    public void setAdditionalParameters(Map<String,String> aParameterMap)
    Adds additional parameters.
    Throws:
      `IllegalArgumentException` - if the parameter map is null or any of its keys is a reserved parameter name.
    Since:
      5.9.0
    See Also:
      - `setAdditionalParameter(String, String)`

  - ### getPerspectiveName

    public final String getPerspectiveName()
    Returns the selected perspective name.
    Since:
      6.0.0

  - ### showAllDataSetFeatures

    public void showAllDataSetFeatures()
    If called, all dataset features will be displayed. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.DataSetFeatures`

  - ### showDataSetFeatures

    public void showDataSetFeatures(List<String> aFeaturesListToDisplay)
    If called, all dataset features will be hidden except those specified by the given list. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.DataSetFeatures`

  - ### showDataSetFeature

    public void showDataSetFeature(String aFeature)
    If called, all dataset features will be hidden except the one specified. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.DataSetFeatures`

  - ### hideAllDataSetFeatures

    public void hideAllDataSetFeatures()
    If called, all dataset features will be hidden.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.DataSetFeatures`

  - ### hideDataSetFeatures

    public void hideDataSetFeatures(List<String> aFeaturesListToHide)
    If called, all dataset features will be displayed except those specified by the given list. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.DataSetFeatures`

  - ### hideDataSetFeature

    public void hideDataSetFeature(String aFeature)
    If called, all dataset features will be displayed except the one specified. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.DataSetFeatures`

  - ### showAllRecordFeatures

    public void showAllRecordFeatures()
    If called, all record features will be displayed. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.RecordFeatures`

  - ### showRecordFeatures

    public void showRecordFeatures(List<String> aFeaturesListToDisplay)
    If called, all record features will be hidden except those specified by the given list. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.RecordFeatures`

  - ### showRecordFeature

    public void showRecordFeature(String aFeature)
    If called, all record features will be hidden except the one specified. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.RecordFeatures`

  - ### hideAllRecordFeatures

    public void hideAllRecordFeatures()
    If called, all record features will be hidden.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.RecordFeatures`

  - ### hideRecordFeatures

    public void hideRecordFeatures(List<String> aFeaturesListToHide)
    If called, all record features will be displayed except those specified by the given list. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.RecordFeatures`

  - ### hideRecordFeature

    public void hideRecordFeature(String aFeature)
    If called, all record features will be displayed except the one specified. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.RecordFeatures`

  - ### showAllViewFeatures

    public void showAllViewFeatures()
    If called, all table or hierarchy features will be displayed. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.ViewFeatures`

  - ### showViewFeatures

    public void showViewFeatures(List<String> aFeaturesListToDisplay)
    If called, all table or hierarchy features will be hidden except those specified by the given list. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.ViewFeatures`

  - ### showViewFeature

    public void showViewFeature(String aFeature)
    If called, all table or hierarchy features will be hidden except the one specified. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.ViewFeatures`

  - ### hideAllViewFeatures

    public void hideAllViewFeatures()
    If called, all table or hierarchy features will be hidden.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.ViewFeatures`

  - ### hideViewFeatures

    public void hideViewFeatures(List<String> aFeaturesListToHide)
    If called, all table or hierarchy features will be displayed except those specified by the given list. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.ViewFeatures`

  - ### hideViewFeature

    public void hideViewFeature(String aFeature)
    If called, all table or hierarchy features will be displayed except the one specified. Note that the user permission will not be ignored.
    Since:
      5.4.0
    See Also:
      - `UIHttpManagerComponent.ViewFeatures`

  - ### setPageSize

    public void setPageSize(int aPageSize)
    Sets the number of rows that will be displayed per page. If a hierarchy is applied using the method `setViewPublication(String)`, this is the number of records that will be shown for each level of the hierarchy.
    Since:
      5.4.2

  - ### getWorkflowView

    public WorkflowView getWorkflowView()
    Returns the workflow view using the service `ServiceKey.WORKFLOW`.
    Since:
      6.0.0