Package com.orchestranetworks.userservice.declaration

# Interface ActivationContext<S extends EntitySelection>

Type Parameters:
  `S` - Defined by the sub-interface to specify the type of entity selection associated with the declared user service.

All Known Subinterfaces:
  `ActivationContextOnAssociation`, `ActivationContextOnAssociationRecord`, `ActivationContextOnDataset`, `ActivationContextOnDataspace`, `ActivationContextOnHierarchy`, `ActivationContextOnHierarchyNode`, `ActivationContextOnRecord`, `ActivationContextOnTableView`, `ActivationContextWithDatasetSet<S>`, `ActivationContextWithSchemaNodeSet<S>`

public interface ActivationContext<S extends EntitySelection>
Allows to define the activation scope and the activation rules of a user service, namely where and when this service is available and can be executed.

### User service activation

User service activation defines on which elements the service can be displayed and executed.

By default, the service is activated on the maximum scope allowed by the type of activation context, see the sub-interfaces documentation for more details. This activation can then be restricted:

- declaratively, see the sub-interfaces documentation for more details.
- dynamically, by using either `ActivationContextOnDataspace.setActivationRule(ServiceActivationRuleForDataspace)` or `ActivationContextWithDatasetSet.setActivationRule(ServiceActivationRuleForDataset)`.

Note: when a service is not activated for a given dataspace or dataset, it will not be displayed in the associated permission UI screens.

### Display in toolbars

By default, the service is automatically displayed in every toolbar location matching the service activation scope. However, this can be refined by using `setDisplayForLocations(ActionDisplaySpec, ToolbarLocation...)`, which allows to specify if and how the service is displayed in the specified locations.

### Permission rules

User service permission rules allow to further restrict the service availability, based on the context.

By default, the service is available in every context where the service is activated. This availability can be restricted by setting a `ServicePermissionRule`. This rule is evaluated every time the service is invoked, either to be displayed or executed.

Since:
  5.8.0
See Also:
  - `UserServiceDeclaration.defineActivation(ActivationContext)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Set<ToolbarLocation>`
  `getAvailableToolbarLocations()`
  Returns all the possible toolbar locations where the current user service declaration can be displayed.
  `void`
  `setDefaultPermission(UserServicePermission aDefaultPermission)`
  Defines the service's default permission (enabled by default).
  `void`
  `setDisplayForAllLocations(ActionDisplaySpec aSpec)`
  Specifies if and how the action launching the service is displayed for all available locations.
  `void`
  `setDisplayForLocations(ActionDisplaySpec aSpec, ToolbarLocation... someToolbarLocations)`
  Specifies if and how the action launching the service is displayed in the specified locations.
  `void`
  `setPermissionRule(ServicePermissionRule<? super S> aRule)`
  Sets a contextual permission rule which will be evaluated at runtime, upon service display or execution.

- ## Method Details

  - ### setDefaultPermission

    void setDefaultPermission(UserServicePermission aDefaultPermission)
    Defines the service's default permission (enabled by default).

    This default permission is used when no permission has been explicitly set for this service to a given profile via UI permissions.

    This method can only be used when declaring a new user service. It has no effect when declaring a service extension.

    See Also:
      - Permissions on services

  - ### setPermissionRule

    void setPermissionRule(ServicePermissionRule<? super S> aRule)
    Sets a contextual permission rule which will be evaluated at runtime, upon service display or execution.

    If it is known that a user service should always be disabled for a given set of datasets or dataspaces, it is recommended to use `setActivationRule(ServiceActivationRuleForX)` instead. Indeed, activation rules have the added benefit to remove the user service from the dataspace and dataset permission UI screens, when deactivated.

    #### ServicePermissionRule Life cycle

    1. The specified rule is instantiated once, when the user service declaration is registered.
    2. During the operational phase: the method `ServicePermissionRule.getPermission(ServicePermissionRuleContext)` is called each time the associated service is potentially displayed or executed in a user interface session.

  - ### setDisplayForAllLocations

    void setDisplayForAllLocations(ActionDisplaySpec aSpec)
    Specifies if and how the action launching the service is displayed for all available locations.

    By default, `ActionDisplaySpec.DISPLAYED` is set for all locations available for this activation.

    See Also:
      - `getAvailableToolbarLocations()`

  - ### setDisplayForLocations

    void setDisplayForLocations(ActionDisplaySpec aSpec, ToolbarLocation... someToolbarLocations)
    Specifies if and how the action launching the service is displayed in the specified locations.

    By default, `ActionDisplaySpec.DISPLAYED` is set for all locations available for this activation.

    To specify an `ActionDisplaySpec` for all available locations, use `setDisplayForAllLocations(ActionDisplaySpec)` instead.

    Throws:
      `IllegalArgumentException` - if no location is specified, or if a location is not available for this activation.
    See Also:
      - `getAvailableToolbarLocations()`

  - ### getAvailableToolbarLocations

    Set<ToolbarLocation> getAvailableToolbarLocations()
    Returns all the possible toolbar locations where the current user service declaration can be displayed. Never returns `null`.
    See Also:
      - `setDisplayForLocations(ActionDisplaySpec, ToolbarLocation...)`