Package com.orchestranetworks.schema

# Interface SchemaExtensionsContext

public interface SchemaExtensionsContext
Context for specifying extensions of a data model. There are 3 types of extensions, namely:

- `AccessRule`/`AccessRuleForCreate` to restrict access on data;
- `ServicePermissionRule` to restrict access on available services;
- `UserServiceDeclaration` to declare a user service.

See Also:
  - `SchemaExtensions.defineExtensions(SchemaExtensionsContext)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `SchemaNode`
  `getSchemaNode()`
  Returns the root node of the data model.
  `<S extends EntitySelection, T extends ActivationContext<S>>
  void`
  `registerUserService(UserServiceDeclaration<S,T> aNewUserServiceDeclaration)`
  Registers a new user service for the current data model in EBX®.
  `void`
  `registerUserServiceExtension(UserServiceExtensionDeclaration aUserServiceExtensionDeclaration)`
  Registers a new user service extension for the current data model in EBX®.
  `void`
  `setAccessRuleForCreateOnNode(Path aPath, AccessRuleForCreate aRule)`
  Sets an `AccessRuleForCreate` on a node without specifying a custom description.
  `void`
  `setAccessRuleForCreateOnNode(Path aPath, AccessRuleForCreate aRule, UserMessage aDescription)`
  Declares that the access to a record node may be restricted by the specified rule while in a record creation context.
  `void`
  `setAccessRuleForCreateOnNodeAndAllDescendants(Path aSubTreePath, boolean includeRoot, AccessRuleForCreate aRule)`
  Sets an `AccessRuleForCreate` on a node subtree without specifying a custom description.
  `void`
  `setAccessRuleForCreateOnNodeAndAllDescendants(Path aSubTreePath, boolean includeRoot, AccessRuleForCreate aRule, UserMessage aDescription)`
  Declares that the access to an element's subtree may be restricted in a record creation context by the specified `AccessRuleForCreate`.
  `void`
  `setAccessRuleOnInstance(AccessRule aRule)`
  Sets an `AccessRule` on a dataset using this schema without specifying a custom description.
  `void`
  `setAccessRuleOnInstance(AccessRule aRule, UserMessage aDescription)`
  Declares that global access to a dataset may be restricted by the specified rule.
  `void`
  `setAccessRuleOnNode(Path aPath, AccessRule aRule)`
  Sets an `AccessRule` on a node without specifying a custom description.
  `void`
  `setAccessRuleOnNode(Path aPath, AccessRule aRule, UserMessage aDescription)`
  Declares that the access to an element may be restricted by the specified rule.
  `void`
  `setAccessRuleOnNodeAndAllDescendants(Path aSubTreePath, boolean includeRoot, AccessRule aRule)`
  Sets an `AccessRule` on a node subtree without specifying a custom description.
  `void`
  `setAccessRuleOnNodeAndAllDescendants(Path aSubTreePath, boolean includeRoot, AccessRule aRule, UserMessage aDescription)`
  Declares that the access to an element's subtree may be restricted by the specified rule.
  `void`
  `setAccessRuleOnOccurrence(Path aTablePath, AccessRule aRule)`
  Sets an `AccessRule` on an table record without specifying a custom description.
  `void`
  `setAccessRuleOnOccurrence(Path aTablePath, AccessRule aRule, UserMessage aDescription)`
  Declares that global access to a table record in the data model may be restricted by the specified rule.
  `void`
  `setServicePermissionRuleOnNode(Path aPathInSchema, ServiceKey aServiceKey, ServicePermissionRule<? extends EntitySelection> aRule)`
  Sets a `ServicePermissionRule` on a node without specifying a custom description.
  `void`
  `setServicePermissionRuleOnNode(Path aPathInSchema, ServiceKey aServiceKey, ServicePermissionRule<? extends EntitySelection> aRule, UserMessage aDescription)`
  Declares that the display and execution of the specified service is conditioned by the specified rule, when invoked on the element referred by the specified path.
  `void`
  `setServicePermissionRuleOnNodeAndAllDescendants(Path aSubTreePathInSchema, ServiceKey aServiceKey, ServicePermissionRule<? extends EntitySelection> aRule)`
  Sets a `ServicePermissionRule` on a node subtree without specifying a custom description.
  `void`
  `setServicePermissionRuleOnNodeAndAllDescendants(Path aSubTreePathInSchema, ServiceKey aServiceKey, ServicePermissionRule<? extends EntitySelection> aRule, UserMessage aDescription)`
  Declares that the display and execution of the specified service is conditioned by the specified rule, for all elements matching the rule's type of `EntitySelection` under the specified data model element.

- ## Method Details

  - ### getSchemaNode

    SchemaNode getSchemaNode()
    Returns the root node of the data model.

  - ### setAccessRuleOnInstance

    void setAccessRuleOnInstance(AccessRule aRule)
    Sets an `AccessRule` on a dataset using this schema without specifying a custom description. This method is equivalent to `setAccessRuleOnInstance(aRule, null)`.
    See Also:
      - `setAccessRuleOnInstance(AccessRule, UserMessage)`

  - ### setAccessRuleOnInstance

    void setAccessRuleOnInstance(AccessRule aRule, UserMessage aDescription)
    Declares that global access to a dataset may be restricted by the specified rule. Note that the `SchemaNode` provided in the rule will always be the root node.

    Attention: Only one `AccessRule` can be associated with a data model regarding the access to its datasets. Thus, if a rule has previously been set using this method, it will be replaced by the current one.

    Parameters:
      `aRule` - the rule to be set
      `aDescription` - a description for the rule. When null, `aRule`'s class name is used.
    Since:
      6.1.2
    See Also:
      - `setAccessRuleOnNode(Path, AccessRule, UserMessage)`
      - `setAccessRuleOnOccurrence(Path, AccessRule, UserMessage)`
      - `AccessRule.getPermission(com.onwbp.adaptation.Adaptation, Session, SchemaNode)`

  - ### setAccessRuleOnNode

    void setAccessRuleOnNode(Path aPath, AccessRule aRule)
    Sets an `AccessRule` on a node without specifying a custom description. This method is equivalent to `setAccessRuleOnNode(aPath, aRule, null)`.
    See Also:
      - `setAccessRuleOnNode(Path, AccessRule, UserMessage)`

  - ### setAccessRuleOnNode

    void setAccessRuleOnNode(Path aPath, AccessRule aRule, UserMessage aDescription)
    Declares that the access to an element may be restricted by the specified rule.

    Attention: Only one `AccessRule` can be specified for a terminal element. As a consequence:

    - if an `AccessRule` has previously been set on the element, it will be replaced by the current one;
    - if the element is not terminal, the rule will be ignored.

    When a rule is not defined at a given level, it is considered to be `AccessRule.ALWAYS_READ_WRITE` at that level.

    At runtime, the effective access permission for an element is the most restrictive permission of the following:

    1. Resolved user-defined permissions: this is the minimum permission computed from the user-defined rules set at each level (dataspace, dataset, table, record and node);
    2. AccessRule for the element's dataset: this is the permission computed by the `AccessRule` attached to the dataset containing the element (see `setAccessRuleOnInstance(AccessRule)`);
    3. AccessRule for the element's record: (only when in a record context) this is the permission computed by the `AccessRule` attached to the record containing the element, if the element is in a table (see `setAccessRuleOnOccurrence(Path, AccessRule)`).
    4. AccessRule for the element: this is the permission computed by the `AccessRule` attached to the element, as set by this method;
    5. AccessRuleForCreate for the element: (only when in a record creation context) this is the permission computed by the `AccessRuleForCreate` attached to the element, as set by `setAccessRuleForCreateOnNode(Path, AccessRuleForCreate)`;
    Parameters:
      `aPath` - the location of the element on which to set the rule
      `aRule` - the rule to be set
      `aDescription` - a description for the rule. When null, `aRule`'s class name is used.
    Since:
      6.1.2
    See Also:
      - Programmatic access right on the data model node

  - ### setAccessRuleOnNodeAndAllDescendants

    void setAccessRuleOnNodeAndAllDescendants(Path aSubTreePath, boolean includeRoot, AccessRule aRule)
    Sets an `AccessRule` on a node subtree without specifying a custom description. This method is equivalent to `setAccessRuleOnNodeAndAllDescendants(aSubTreePath, includeRoot, aRule, null)`.
    See Also:
      - `setAccessRuleOnNodeAndAllDescendants(Path, boolean, AccessRule, UserMessage)`

  - ### setAccessRuleOnNodeAndAllDescendants

    void setAccessRuleOnNodeAndAllDescendants(Path aSubTreePath, boolean includeRoot, AccessRule aRule, UserMessage aDescription)
    Declares that the access to an element's subtree may be restricted by the specified rule. Only terminal elements will be affected by the specified rule.

    Attention: Only one `AccessRule` can be specified for a terminal element. As a consequence, if an `AccessRule` has previously been set on any node in the specified sub-tree, it will be replaced by the specified one.

    Parameters:
      `aSubTreePath` - the root of the sub-tree on which to set the rule
      `includeRoot` - specifies whether the root is also to have the rule set
      `aRule` - the rule to set
      `aDescription` - a description for the rule. When null, `aRule`'s class name is used.
    Since:
      6.1.2
    See Also:
      - `setAccessRuleOnNode(Path, AccessRule, UserMessage)`

  - ### setAccessRuleForCreateOnNode

    void setAccessRuleForCreateOnNode(Path aPath, AccessRuleForCreate aRule)
    Sets an `AccessRuleForCreate` on a node without specifying a custom description. This method is equivalent to `setAccessRuleForCreateOnNode(aPath, aRule, null)`.
    Since:
      5.9.0
    See Also:
      - `setAccessRuleForCreateOnNode(Path, AccessRuleForCreate, UserMessage)`

  - ### setAccessRuleForCreateOnNode

    void setAccessRuleForCreateOnNode(Path aPath, AccessRuleForCreate aRule, UserMessage aDescription)
    Declares that the access to a record node may be restricted by the specified rule while in a record creation context.

    See `setAccessRuleOnNode(Path, AccessRule)` for more information about permission evaluation.

    Attention: Only one `AccessRuleForCreate` can be specified for a terminal element under a table. As a consequence:

    - if an `AccessRuleForCreate` has previously been set on the element, it will be replaced by the current one;
    - if the element is not terminal or not under a table, a compilation error is added.

    Parameters:
      `aPath` - the location of the element on which to set the rule
      `aRule` - the rule to be set
      `aDescription` - a description for the rule. When null, `aRule`'s class name is used.
    Since:
      6.1.2
    See Also:
      - Programmatic access right on the data model node

  - ### setAccessRuleForCreateOnNodeAndAllDescendants

    void setAccessRuleForCreateOnNodeAndAllDescendants(Path aSubTreePath, boolean includeRoot, AccessRuleForCreate aRule)
    Sets an `AccessRuleForCreate` on a node subtree without specifying a custom description. This method is equivalent to `setAccessRuleOnNodeAndAllDescendants(aSubTreePath, includeRoot, aRule, null)`.
    Since:
      5.9.0
    See Also:
      - `setAccessRuleForCreateOnNodeAndAllDescendants(Path, boolean, AccessRuleForCreate, UserMessage)`

  - ### setAccessRuleForCreateOnNodeAndAllDescendants

    void setAccessRuleForCreateOnNodeAndAllDescendants(Path aSubTreePath, boolean includeRoot, AccessRuleForCreate aRule, UserMessage aDescription)
    Declares that the access to an element's subtree may be restricted in a record creation context by the specified `AccessRuleForCreate`. Only record terminal nodes will be affected by the specified rule.

    Attention: Only one `AccessRuleForCreate` can be specified for a terminal element under a table. As a consequence, if an `AccessRuleForCreate` has previously been set on any node in the specified sub-tree, it will be replaced by the specified one.

    Parameters:
      `aSubTreePath` - the root of the sub-tree on which to set the rule
      `includeRoot` - specifies whether the root is also to have the rule set
      `aRule` - the rule to set
      `aDescription` - a description for the rule. When null, `aRule`'s class name is used.
    Since:
      6.1.2
    See Also:
      - `setAccessRuleForCreateOnNode(Path, AccessRuleForCreate, UserMessage)`

  - ### setAccessRuleOnOccurrence

    void setAccessRuleOnOccurrence(Path aTablePath, AccessRule aRule)
    Sets an `AccessRule` on an table record without specifying a custom description. This method is equivalent to `setAccessRuleOnOccurrence(aTablePath, aRule, null)`.
    See Also:
      - `setAccessRuleOnOccurrence(Path, AccessRule, UserMessage)`

  - ### setAccessRuleOnOccurrence

    void setAccessRuleOnOccurrence(Path aTablePath, AccessRule aRule, UserMessage aDescription)
    Declares that global access to a table record in the data model may be restricted by the specified rule.

    Attention 1: When dealing with large volume, it is highly recommended to use scripting record access rule instead.

    Attention 2: Only one rule can be associated with a table at a given path for access to its records. Thus, if a rule has already been set, it will be replaced by the current one.

    At runtime, the effective access permission to a table record is the most restrictive permission of the following:

    1. AccessRule for the table's dataset: these are the rights that are computed by the `AccessRule` attached to the dataset containing the table (see `setAccessRuleOnInstance(AccessRule)`);
    2. AccessRule for the element's record: these are the rights that are computed by the `AccessRule` and/or scripting record access rule attached to the record containing the element.

    When a rule is not defined at a given level, it is considered to be `AccessRule.ALWAYS_READ_WRITE` at that level.

    Parameters:
      `aTablePath` - location of the table element
      `aRule` - the rule to set
      `aDescription` - a description for the rule. When null, `aRule`'s class name is used.
    Since:
      6.1.2
    See Also:
      - `AccessRule.getPermission(com.onwbp.adaptation.Adaptation, Session, SchemaNode)`

  - ### setServicePermissionRuleOnNode

    void setServicePermissionRuleOnNode(Path aPathInSchema, ServiceKey aServiceKey, ServicePermissionRule<? extends EntitySelection> aRule)
    Sets a `ServicePermissionRule` on a node without specifying a custom description. This method is equivalent to `setServicePermissionRuleOnNode(aPathInSchema, aServiceKey, aRule, null)`.
    Since:
      5.8.0
    See Also:
      - `setServicePermissionRuleOnNode(Path, ServiceKey, ServicePermissionRule, UserMessage)`

  - ### setServicePermissionRuleOnNode

    void setServicePermissionRuleOnNode(Path aPathInSchema, ServiceKey aServiceKey, ServicePermissionRule<? extends EntitySelection> aRule, UserMessage aDescription)
    Declares that the display and execution of the specified service is conditioned by the specified rule, when invoked on the element referred by the specified path. The rule can only restrict the service availability.

    Attention: Only one rule can be associated with a path. Thus, if a rule has previously been set on the element, it will be replaced by the current one.

    #### Possible types of rule by element

    When the element specified by the path is a dataset, the specified rule can only be a `ServicePermissionRule<DatasetEntitySelection>`, in which case the rule will be evaluated when the selection is this dataset.

    When the element specified by the path is a table, the specified rule can either be:

    - a `ServicePermissionRule<TableViewEntitySelection>` or a `ServicePermissionRule<RecordEntitySelection>`, in which case the rule will be evaluated when the selection is:
      - this table;
      - a record selection or single record of this table;
      - an association view linking to this table;
      - a single record in an association view linking to this table;
      - a hierarchy with this table as target table;
      - a hierarchy node representing a record of this table.

      For a `ServicePermissionRule<RecordEntitySelection>`, the provided context is more limited than the one provided in a `ServicePermissionRule<TableViewEntitySelection>`, but it is also easier to use when working on a single record base.

    - a `ServicePermissionRule<HierarchyEntitySelection>`, in which case the rule will only be evaluated when the selection is a hierarchy with this table as target table.
    - a `ServicePermissionRule<HierarchyNodeEntitySelection>`, in which case the rule will only be evaluated when the selection is a hierarchy node representing a record of this table.

    When the element specified by the path is an association, the specified rule can either be:

    - a `ServicePermissionRule<AssociationEntitySelection>`, in which case the rule will only be evaluated when the selection is this association.
    - a `ServicePermissionRule<AssociationRecordEntitySelection>`, in which case the rule will only be evaluated when the selection is a linked record by this association.

    #### Compilation errors

    A data model compilation error is added:

    - if the element referred by the specified path is not the data model's root, a table, or an association.
    - if the permission rule `EntitySelection` parameter does not match the element referred by the specified path (see previous section).
    Parameters:
      `aPathInSchema` - the location of the element on which to set the rule
      `aServiceKey` - the key of the service on which the rule will apply
      `aRule` - the rule to be set
      `aDescription` - a description for the rule. When null, `aRule`'s class name is used.
    Throws:
      `IllegalArgumentException` - if:
      - specified `Path` is `null`.
      - specified `ServiceKey` is `null`.
      - specified `ServicePermissionRule` is `null`.
    Since:
      6.1.2
    See Also:
      - `ServicePermissionRule.getPermission(ServicePermissionRuleContext)`
      - Programmatic activation on service
      - Resolving permissions for services

  - ### setServicePermissionRuleOnNodeAndAllDescendants

    void setServicePermissionRuleOnNodeAndAllDescendants(Path aSubTreePathInSchema, ServiceKey aServiceKey, ServicePermissionRule<? extends EntitySelection> aRule)
    Sets a `ServicePermissionRule` on a node subtree without specifying a custom description. This method is equivalent to `setServicePermissionRuleOnNodeAndAllDescendants(aSubTreePathInSchema, aServiceKey, aRule, null)`.
    Since:
      5.8.0
    See Also:
      - `setServicePermissionRuleOnNodeAndAllDescendants(Path, ServiceKey, ServicePermissionRule, UserMessage)`

  - ### setServicePermissionRuleOnNodeAndAllDescendants

    void setServicePermissionRuleOnNodeAndAllDescendants(Path aSubTreePathInSchema, ServiceKey aServiceKey, ServicePermissionRule<? extends EntitySelection> aRule, UserMessage aDescription)
    Declares that the display and execution of the specified service is conditioned by the specified rule, for all elements matching the rule's type of `EntitySelection` under the specified data model element.

    Attention: Only one rule can be associated with an element. Thus, if a rule has previously been set for any element in the specified sub-tree, it will be replaced by the specified rule. For this reason, the order in which rules are set is important.

    #### Matching elements by type of rule

    The rule will be set on table elements only, when the specified rule is either:

    - a `ServicePermissionRule<TableViewEntitySelection>`
    - a `ServicePermissionRule<RecordEntitySelection>`,
    - a `ServicePermissionRule<HierarchyEntitySelection>`
    - a `ServicePermissionRule<HierarchyNodeEntitySelection>`

    The rule will be set on association elements only, when the specified rule is either:

    - a `ServicePermissionRule<AssociationEntitySelection>`
    - a `ServicePermissionRule<AssociationRecordEntitySelection>`
    Parameters:
      `aSubTreePathInSchema` - the root of the sub-tree on which to set the rule
      `aServiceKey` - the key of the service on which the rule will apply
      `aRule` - the rule to set
      `aDescription` - a description for the rule. When null, `aRule`'s class name is used.
    Since:
      6.1.2
    See Also:
      - `setServicePermissionRuleOnNode(Path, ServiceKey, ServicePermissionRule, UserMessage)`
      - `ServicePermissionRule.getPermission(ServicePermissionRuleContext)`

  - ### registerUserService

    <S extends EntitySelection, T extends ActivationContext<S>> void registerUserService(UserServiceDeclaration<S,T> aNewUserServiceDeclaration)
    Registers a new user service for the current data model in EBX®.
    Since:
      5.8.0

  - ### registerUserServiceExtension

    void registerUserServiceExtension(UserServiceExtensionDeclaration aUserServiceExtensionDeclaration)
    Registers a new user service extension for the current data model in EBX®.

    Only built-in services and services declared in the current data model can be extended using this method.

    Since:
      5.8.0