Package de.aristaflow.adept2.core.orgmodelmanager

Interface PolicyResolution

public interface PolicyResolution
This interface provides methods to deal with OrgPolicies (Bearbeiterformeln), i.e. to check their syntax, resolve them and test whether a certain OrgPosition (Stelle) and/or Agent (Mitarbeiter) matches a policy.

When ModelExplorer is used to implement this interface, it must be ensured that all OrgModelExceptions are caught! If an OrgModelException is caught, checkSyntax(String, boolean, boolean) and checkResolvability(SessionToken, String, boolean, boolean) should just return false whereas all other methods should throw a PolicyResolutionException in response.

This policy resolution allows for extending the normal policy resolution by the means to dynamically register org policy script handlers at runtime additionally to the corresponding registered plugins. Note that an existing plugin will be preferred to a dynamically registered OrgPolicyScriptService and this to a dynamically registered OrgPolicyScriptHandler.

  • Method Details

    • checkSyntax

      OrgPolicyReport checkSyntax(String orgPolicy, boolean createFullReport, boolean rejectParameterReferences)
      This method checks whether the syntax of the given OrgPolicy is correct. However, it doesn't verify that the policy is actually resolvable. It may e.g. contain attributes that don't exist. Path completion is also not validated. To test whether a policy is actually resolvable - in the context of the underlying organisational model - use checkResolvability(SessionToken, String, boolean, boolean).

      For a complete list of what is tested, see OrgPolicyParser.parse(String, OrgPolicyReport, de.aristaflow.adept2.core.orgmodelmanager.parser.TokenInfoContainer).

      Parameters:
      orgPolicy - the OrgPolicy to be checked
      createFullReport - if false only the overall result will be set (OrgPolicyReport.ResultType.OK or OrgPolicyReport.ResultType.ERROR)
      rejectParameterReferences - whether parameter references should be treated as errors
      Returns:
      a report that will (depending on the boolean parameter) be filled with an entry for each encountered problem; at least the overall result will be set

    • checkResolvability

      OrgPolicyReport checkResolvability(SessionToken session, String orgPolicy, boolean createFullReport, boolean rejectParameterReferences) throws DataSourceException
      Tests whether the given OrgPolicy is resolvable for the current state of the OrgModel. This includes a syntax check like in checkSyntax(String, boolean, boolean).

      Additionally to what checkSyntax(String, boolean, boolean) checks, this parse method will...

      • check whether incomplete paths can be completed down to Agent (if PathCompletion is specified)
      • verify if local appearances of an entity type are valid (only within SubstitutionRule a foreign entity type can be accessed, namely Role)
      • verify whether attributes actually exist
      • verify whether the comparison operator can be used to compare the data type of the value literal to the data type of the attribute
      Parameters:
      session - The session which is used to check for access rights on this method.
      orgPolicy - the OrgPolicy to be checked
      createFullReport - if false only the overall result will be set (OrgPolicyReport.ResultType.OK or OrgPolicyReport.ResultType.ERROR)
      rejectParameterReferences - whether parameter references should be treated as errors
      Returns:
      a report that will (depending on the boolean parameter) be filled with an entry for each encountered problem; at least the overall result will be set
      Throws:
      DataSourceException - when an unrecoverable error occurs while accessing the data source

    • resolvePolicy

      Set<QualifiedAgent> resolvePolicy(SessionToken session, String orgPolicy) throws PolicyResolutionException, DataSourceException
      Resolves an OrgPolicy and returns all matching tuples of OrgPositions and Agents (or rather their IDs) as a list of QualifiedAgents.
      Parameters:
      session - The session which is used to check for access rights on this method.
      orgPolicy - the OrgPolicy (Bearbeiterformel) that is be resolved
      Returns:
      list of QualifiedAgents
      Throws:
      PolicyResolutionException - when the provided OrgPolicy is syntactically or semantically incorrect (this is a runtime exception)
      DataSourceException - when an unrecoverable error occurs while accessing the data source

    • resolvePolicyIterator

      RemoteIterator<List<QualifiedAgent>> resolvePolicyIterator(SessionToken session, String orgPolicy) throws PolicyResolutionException, DataSourceException
      The same as resolvePolicy(SessionToken, String) but with partial retrieval of the qualified agents.
      Parameters:
      session - The session which is used to check for access rights on this method.
      orgPolicy - the OrgPolicy (Bearbeiterformel) that is be resolved
      Returns:
      List of QualifiedAgents as iterator. The caller is responsible for closing.
      Throws:
      PolicyResolutionException - when the provided OrgPolicy is syntactically or semantically incorrect (this is a runtime exception)
      DataSourceException - when an unrecoverable error occurs while accessing the data source

    • isMember

      boolean isMember(SessionToken session, long orgPositionID, String orgPolicy) throws PolicyResolutionException, DataSourceException
      Semantically this method tests whether the given OrgPosition appears in the result list of resolvePolicy(SessionToken, String) for the specified OrgPolicy. However, this doesn't mean that the actual implementation really will or has to call resolvePolicy(SessionToken, String).
      Parameters:
      session - The session which is used to check for access rights on this method.
      orgPositionID - the OrgPosition's ID to be checked against the OrgPolicy
      orgPolicy - The OrgPolicy to be resolved. This may also be a script policy.
      Returns:
      whether the given OrgPosition appears in the result list of the resolved OrgPolicy
      Throws:
      PolicyResolutionException - when the provided OrgPolicy is syntactically or semantically incorrect
      DataSourceException - when an unrecoverable error occurs while accessing the data source

    • isMember

      boolean isMember(SessionToken session, String agentUserName, String orgPolicy) throws PolicyResolutionException, DataSourceException
      Semantically this method tests whether the given Agent appears in the result list of resolvePolicy(SessionToken, String) for the specified OrgPolicy. However, this doesn't mean that the actual implementation really will or has to call resolvePolicy(SessionToken, String).
      Parameters:
      session - The session which is used to check for access rights on this method.
      agentUserName - the (unique) Agent's username to be checked against the OrgPolicy
      orgPolicy - The OrgPolicy to be resolved. This may also be a script policy.
      Returns:
      whether the given Agent matches the given OrgPolicy
      Throws:
      PolicyResolutionException - when the provided OrgPolicy is syntactically or semantically incorrect
      DataSourceException - when an unrecoverable error occurs while accessing the data source

    • isMember

      boolean isMember(SessionToken session, long orgPositionID, String agentUserName, String orgPolicy) throws PolicyResolutionException, DataSourceException
      Semantically this method tests whether the given tuple of Agent and OrgPosition is contained in the result list of resolvePolicy(SessionToken, String) for the specified OrgPolicy. However, this doesn't mean that the actual implementation really will or has to call resolvePolicy(SessionToken, String).
      Parameters:
      session - The session which is used to check for access rights on this method.
      orgPositionID - the OrgPosition's ID to be checked against the OrgPolicy
      agentUserName - the (unique) Agent's username to be checked against the OrgPolicy
      orgPolicy - The OrgPolicy to be resolved. This may also be a script policy.
      Returns:
      whether the given tuple of Agent and OrgPosition is matched by the given OrgPolicy
      Throws:
      PolicyResolutionException - when the provided OrgPolicy is syntactically or semantically incorrect
      DataSourceException - when an unrecoverable error occurs while accessing the data source

    • registerOrgPolicyScriptService

      SortedMap<Integer,URI[]> registerOrgPolicyScriptService(SessionToken session, String scriptType, URI[] orgPolicyScriptService, boolean replace, boolean append)
      Registers the OrgPolicyScriptService for the designated script type. If there is already a service registered for the designated script type, the designated service will be either be ignored, replace all existing org policy script services or be appended at the end of the list of known services. When trying to append a service already known (i. e. the URIs are already registered), this service will be silently ignored.
      The URIs will be persisted, so that a server restart or a cluster node role change will be transparent for the caller.

      Note that registering/appending many org policy services may lead to slow policy resolution. This in turn may lead to aborted connection for requests that require a policy resolution – which a lot of requests do.

      Parameters:
      session - The session for checking access rights.
      scriptType - The type of the script for which to register an org policy script service.
      orgPolicyScriptService - The (URIs of the) org policy script service providing the org policy script handler.
      replace - Whether to replace an existing org policy script service for the designated scriptType with the designated org policy script service. Replacing will ignore append.
      append - Whether to append the designated org policy script service as an alternative for an existing org policy script service for the designated scriptType. At runtime the list of org policy script services will be iterated, the first successful org policy resolution will apply. Afterwards this will be used as long as it is available; the list will not be iterated again until the chosen handler is no longer available.
      Returns:
      The URIs of the org policy services which are currently registered for the designated script type indexed by the corresponding position in the list of all registered services. These may be the designated URI, they may be appended to previously registered ones or it may be null in case registering the designated service has not been successful.

    • unregisterOrgPolicyScriptService

      SortedMap<Integer,URI[]> unregisterOrgPolicyScriptService(SessionToken session, String scriptType, URI[] orgPolicyScriptService)
      Unregisters the OrgPolicyScriptService for the designated script type from this policy resolution. Its handler will no longer be used for resolving policies. Unregistering will only be successful, if the designated URIs are registered for the designated script type. Otherwise this call will be ignored.
      Parameters:
      session - The session for checking access rights.
      scriptType - The type of the script for which to unregister an org policy script service.
      orgPolicyScriptService - The (URIs of the) org policy script service providing the org policy script handler which to unregister.
      Returns:
      The URIs of the org policy script services which are currently registered for the designated script type after unregistering the designated org policy service indexed by the corresponding position in the list of all registered services. If this method call unregisters the designated script type completely, an empty map will be returned. If the designated script type is not registered, null will be returned.

    • registerOrgPolicyHandler

      boolean registerOrgPolicyHandler(SessionToken session, String scriptType, OrgPolicyScriptHandler handler, boolean replace)
      Registers the designated org policy script handler for the designated script type. If there is already a handler registered for the designated script type, the designated handler will be ignored.
      Contrary to registerOrgPolicyScriptService(SessionToken, String, URI[], boolean, boolean) the designated handler will not survive a server restart or a cluster node role change. You will have to re-register it.
      Parameters:
      session - The session for checking access rights.
      scriptType - The type of the script for which to register an org policy script handler.
      handler - The org policy script handler to register for the designated script type.
      replace - Whether to replace an existing org policy handler for the designated scriptType with the designated handler.
      Returns:
      Whether the designated handler has been registered (or not in case there is already a handler registered for the designated script type).

    • unregisterOrgPolicyHandler

      boolean unregisterOrgPolicyHandler(SessionToken session, String scriptType, OrgPolicyScriptHandler handler)
      Unregisters the org policy script handler for the designated script type from this policy resolution. The handler will no longer be used for resolving policies.
      Parameters:
      session - The session for checking access rights.
      scriptType - The type of the script for which to unregister an org policy script handler.
      handler - The org policy script handler which to unregister for the designated script type.
      Returns:
      Whether the designated handler has been successfully unregistered (or not in case there is no corresponding handler registered).