Package com.orchestranetworks.ui

# Interface UIResourceLocator

All Known Subinterfaces:
  `UIAjaxContext`, `UIComponentWriter`, `UIFormContext`, `UIFormPaneWriter`, `UIFormWriter`, `UILabelRendererForHierarchyContext`, `UIResponseContext`, `UIServiceComponentWriter`, `UITableFilterResponseContext`, `UserServiceDisplayConfigurator`, `UserServiceEventContext`, `UserServiceGetCreatedRecordContext<S>`, `UserServiceInitializeContext<S>`, `UserServicePaneWriter`, `UserServiceRawPaneWriter`, `UserServiceResourceLocator`, `UserServiceWriter`, `WidgetWriter`, `WidgetWriterForList`

All Known Implementing Classes:
  `ServiceContext`

public interface UIResourceLocator
This interface defines methods to build URLs that change the entity in the current navigation context and access various types of resources (Web Component, Ajax component, static web resources).

Since:
  5.2.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `UIHttpManagerComponent`
  `createWebComponentForRootSession()`
  Returns a factory for creating a URL that, when used, creates a new navigation context in a separate root user session (namely, a Web Component).
  `UIHttpManagerComponent`
  `createWebComponentForSubSession()`
  Returns a factory for creating a URL that, when used, creates a new navigation context in a separate sub-session (namely, a Web Component).
  `String`
  `getURLForAjaxComponent(String ajaxComponentName)`
  Returns the URL for the specified Ajax component.
  `String`
  `getURLForAjaxComponent(String ajaxComponentName, Map<String,String> parameters)`
  Returns the URL for the specified Ajax component.
  `String`
  `getURLForPerspectiveSelection(String aPerspectiveName)`
  Returns a URL that, when used, changes the current navigation context to the specified perspective.
  `String`
  `getURLForPerspectiveSelection(String aPerspectiveName, String aPerspectiveActionName)`
  Returns a URL that, when used, changes the current navigation context to the specified perspective action.
  `String`
  `getURLForResource(SchemaNode aSchemaNode, Object aValue)`
  Returns the URL of the web resource specified by the value of a resource type node.
  `String`
  `getURLForResource(ResourceType aResourceType, String aResourceName)`
  Returns the URL of the specified web resource in the current module (that is, the module of the current adaptation) for the current session locale.
  `String`
  `getURLForResource(ResourceType aResourceType, String aResourceName, Locale aLocale)`
  Returns the URL of the specified web resource in the current module (that is, the module of the current adaptation) for the specified locale.
  `String`
  `getURLForResource(String aResourcePath)`
  Returns the URL string for the specified web resource.
  `String`
  `getURLForResource(String aModuleName, ResourceType aResourceType, String aResourceName, Locale aLocale)`
  Returns the URL of the specified web resource.
  `String`
  `getURLForRest(String aPath, URLQuery aQuery)`
  Returns the REST URL string for the specified path and query.
  `String`
  `getURLForSelection(Adaptation aDataSetOrRecord)`
  Returns a URL that, when used, changes the current navigation context to the specified dataset or record.
  `String`
  `getURLForSelection(AdaptationHome aDataSpaceOrSnapshot)`
  Returns a URL that, when used, changes the current navigation context to the specified dataspace or snapshot.
  `String`
  `getURLForSelection(Adaptation aDataSetOrRecord, Path aPath)`
  Returns a URL that, when used, changes the current navigation context to the specified node and dataset or record.
  `String`
  `getURLForSelection(WorkflowView aWorkflowView)`
  Returns a URL that, when used, changes the current navigation context to the specified data workflows section.
  `String`
  `getURLForSelection(WorkItemKey aWorkItemKey)`
  Returns a URL that, when used, changes the current navigation context to the specified work item.
  `String`
  `getURLForSelection(WorkItemKey aWorkItemKey, boolean shouldAllocateAndStart)`
  Returns a URL that, when used, changes the current navigation context to the specified work item.
  `String`
  `getURLForViewSelection(Adaptation instance, String viewPublication)`
  Returns a URL that, when used, changes the current navigation context to the specified custom view in the specified dataset.

- ## Method Details

  - ### createWebComponentForRootSession

    UIHttpManagerComponent createWebComponentForRootSession()
    Returns a factory for creating a URL that, when used, creates a new navigation context in a separate root user session (namely, a Web Component).

    When the property `ebx.servlet.useLocalUrl` in the EBX® main configuration file is set to 'true', the URL obtained can be used as a permanent link (permalink) to access the current EBX® repository.

    The authentication must be properly managed by passing adequate parameters or the end user will need to authenticate by logging in.

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

    Since:
      5.2.5
    See Also:
      - `createWebComponentForSubSession()`
      - `getURLForSelection(Adaptation)`

  - ### createWebComponentForSubSession

    UIHttpManagerComponent createWebComponentForSubSession()
    Returns a factory for creating a URL that, when used, creates a new navigation context 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)`.

    Since:
      5.2.5
    See Also:
      - `createWebComponentForRootSession()`
      - `getURLForSelection(Adaptation)`

  - ### getURLForSelection

    String getURLForSelection(Adaptation aDataSetOrRecord)
    Returns a URL that, when used, changes the current navigation context to the specified dataset or record.

    It is recommended to keep the link target in the same window. In the case where the current navigation context must remain unchanged, a `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)`.

    See Also:
      - `createWebComponentForSubSession()`
      - `UIHttpManagerComponent.selectInstanceOrOccurrence(Adaptation)`

  - ### getURLForViewSelection

    String getURLForViewSelection(Adaptation instance, String viewPublication)
    Returns a URL that, when used, changes the current navigation context to the specified custom view in the specified dataset.

    It is recommended to keep the link target in the same window. In the case where the current navigation context must remain unchanged, a `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)`.

    Since:
      5.2.4
    See Also:
      - `createWebComponentForSubSession()`
      - `UIHttpManagerComponent.selectInstanceOrOccurrence(Adaptation)`
      - `UIHttpManagerComponent.setViewPublication(String)`

  - ### getURLForSelection

    String getURLForSelection(Adaptation aDataSetOrRecord, Path aPath)
    Returns a URL that, when used, changes the current navigation context to the specified node and dataset or record.

    It is recommended to keep the target of the link in the same window. In the case where the current navigation context must remain unchanged, a `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)`.

    See Also:
      - `createWebComponentForSubSession()`
      - `UIHttpManagerComponent.selectNode(Adaptation, Path)`

  - ### getURLForSelection

    String getURLForSelection(AdaptationHome aDataSpaceOrSnapshot)
    Returns a URL that, when used, changes the current navigation context to the specified dataspace or snapshot.

    It is recommended to keep the target of the link in the same window. In the case where the current navigation context must remain unchanged, a `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)`.

    See Also:
      - `createWebComponentForSubSession()`
      - `UIHttpManagerComponent.selectHome(AdaptationHome)`
      - `UIComponentWriter.buildButtonPreview(String)`

  - ### getURLForSelection

    String getURLForSelection(WorkItemKey aWorkItemKey)
    Returns a URL that, when used, changes the current navigation context to the specified work item. In this case, the workflow section will be set to ``WorkflowView.INBOX``

    It is recommended to keep the target of the link in the same window.

    Parameters:
      `aWorkItemKey` - key of the work item to be selected
    Since:
      5.2.3

  - ### getURLForSelection

    String getURLForSelection(WorkItemKey aWorkItemKey, boolean shouldAllocateAndStart)
    Returns a URL that, when used, changes the current navigation context to the specified work item. In this case, the workflow section will be set to ``WorkflowView.INBOX``

    It is recommended to keep the target of the link in the same window.

    Parameters:
      `aWorkItemKey` - key of the work item to be selected
      `shouldAllocateAndStart` - 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.
    Since:
      5.4.3

  - ### getURLForSelection

    String getURLForSelection(WorkflowView aWorkflowView)
    Returns a URL that, when used, changes the current navigation context to the specified data workflows section.

    It is recommended to keep the target of the link in the same window.

    Parameters:
      `aWorkflowView` - key of the workflow view to be selected
    Since:
      5.4.3

  - ### getURLForPerspectiveSelection

    String getURLForPerspectiveSelection(String aPerspectiveName)
    Returns a URL that, when used, changes the current navigation context to the specified perspective.

    It is recommended to keep the target of the link in the same window.

    Parameters:
      `aPerspectiveName` - name of the perspective to be selected
    Since:
      5.9.0 fix B

  - ### getURLForPerspectiveSelection

    String getURLForPerspectiveSelection(String aPerspectiveName, String aPerspectiveActionName)
    Returns a URL that, when used, changes the current navigation context to the specified perspective action.

    It is recommended to keep the target of the link in the same window.

    Parameters:
      `aPerspectiveName` - name of the perspective to be selected
      `aPerspectiveActionName` - name of the perspective action to be selected
    Since:
      5.9.0 fix B

  - ### getURLForAjaxComponent

    String getURLForAjaxComponent(String ajaxComponentName)
    Returns the URL for the specified Ajax component.
    Parameters:
      `ajaxComponentName` - name of the Ajax component declared either in the data model or in the module.
    See Also:
      - `UIAjaxComponent`

  - ### getURLForAjaxComponent

    String getURLForAjaxComponent(String ajaxComponentName, Map<String,String> parameters)
    Returns the URL for the specified Ajax component.
    Parameters:
      `ajaxComponentName` - name of the Ajax component declared either in the data model or in the module. If the Ajax component is declared in the module, the name should be prefixed by the module's name and '@' for example `module_name@ajax_component_name`.
      `parameters` - map defining HTTP parameters that are passed in the Ajax request. It maps HTTP parameter names with their values.
    See Also:
      - `UIAjaxComponent`

  - ### getURLForResource

    String getURLForResource(String aResourcePath)
    Returns the URL string for the specified web resource.

    The resource must be in the same web application as the service.

    Parameters:
      `aResourcePath` - must begin with a "/" and is interpreted as relative to the module (web application) root.

  - ### getURLForResource

    String getURLForResource(ResourceType aResourceType, String aResourceName)
    Returns the URL of the specified web resource in the current module (that is, the module of the current adaptation) for the current session locale.
    See Also:
      - `getURLForResource(ResourceType, String, Locale)`

  - ### getURLForResource

    String getURLForResource(ResourceType aResourceType, String aResourceName, Locale aLocale)
    Returns the URL of the specified web resource in the current module (that is, the module of the current adaptation) for the specified locale.
    Throws:
      `UnsupportedOperationException` - if the resource type is internal (not accessible from HTTP).

  - ### getURLForResource

    String getURLForResource(String aModuleName, ResourceType aResourceType, String aResourceName, Locale aLocale) throws ModuleNotFoundException
    Returns the URL of the specified web resource.
    Throws:
      `UnsupportedOperationException` - if the resource type is internal (not accessible from HTTP).
      `ModuleNotFoundException` - if the specified name does not correspond to a module.

  - ### getURLForResource

    String getURLForResource(SchemaNode aSchemaNode, Object aValue) throws IllegalArgumentException
    Returns the URL of the web resource specified by the value of a resource type node.
    Parameters:
      `aSchemaNode` - the schema node where the value comes from. The schema node must be an `osd:resource` type.
      `aValue` - the value of the `osd:resource` type.
    Throws:
      `IllegalArgumentException` - if the schema node or the value is not an `osd:resource` type.
    Since:
      5.8.0
    See Also:
      - Resource type documentation
      - `UIContext.getNode()`
      - `UIContext.getValue()`
      - `UIFormContext.getValueContext()`
      - `ValueContext.getValue()`
      - `Adaptation.get(Path)`

  - ### getURLForRest

    String getURLForRest(String aPath, URLQuery aQuery) throws IllegalArgumentException
    Returns the REST URL string for the specified path and query.

    The REST service will be called using the current user's credentials.

    Parameters:
      `aPath` - the path to the REST resource. It must start with a slash character '/' and not contain the host (sample: `/ebx-dataservices/rest/{category}/v1/{dataspace}/{dataset}/{pathInDataSet}`)
      `aQuery` - a list of URL query parameters that is added to the resulting URL. May be `null`.
    Throws:
      `IllegalArgumentException` - if the provided REST resource path is `null` or its format is incorrect.
    Since:
      5.8.1
    See Also:
      - User service and REST data services
      - RESTful operations
      - JSON extended format
      - JSON compact format
      - `RestConstants`