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 Summary

Modifier and Type	Method and Description
OrgPolicyReport	checkResolvability(SessionToken session, java.lang.String orgPolicy, boolean createFullReport, boolean rejectParameterReferences) Tests whether the given OrgPolicy is resolvable for the current state of the OrgModel.
OrgPolicyReport	checkSyntax(java.lang.String orgPolicy, boolean createFullReport, boolean rejectParameterReferences) This method checks whether the syntax of the given OrgPolicy is correct.
boolean	isMember(SessionToken session, long orgPositionID, java.lang.String orgPolicy) Semantically this method tests whether the given OrgPosition appears in the result list of resolvePolicy(SessionToken, String) for the specified OrgPolicy.
boolean	isMember(SessionToken session, long orgPositionID, java.lang.String agentUserName, java.lang.String orgPolicy) 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.
boolean	isMember(SessionToken session, java.lang.String agentUserName, java.lang.String orgPolicy) Semantically this method tests whether the given Agent appears in the result list of resolvePolicy(SessionToken, String) for the specified OrgPolicy.
boolean	registerOrgPolicyHandler(SessionToken session, java.lang.String scriptType, OrgPolicyScriptHandler handler, boolean replace) Registers the designated org policy script handler for the designated script type.
java.util.List<java.net.URI[]>	registerOrgPolicyScriptService(SessionToken session, java.lang.String scriptType, java.net.URI[] orgPolicyScriptService, boolean replace, boolean append) Registers the OrgPolicyScriptService for the designated script type.
java.util.Set<QualifiedAgent>	resolvePolicy(SessionToken session, java.lang.String orgPolicy) Resolves an OrgPolicy and returns all matching tuples of OrgPositions and Agents (or rather their IDs) as a list of QualifiedAgents.
RemoteIterator<java.util.List<QualifiedAgent>>	resolvePolicyIterator(SessionToken session, java.lang.String orgPolicy) The same as resolvePolicy(SessionToken, String) but with partial retrieval of the qualified agents.
boolean	unregisterOrgPolicyHandler(SessionToken session, java.lang.String scriptType, OrgPolicyScriptHandler handler) Unregisters the org policy script handler for the designated script type from this policy resolution.
java.util.List<java.net.URI[]>	unregisterOrgPolicyScriptService(SessionToken session, java.lang.String scriptType, java.net.URI[] orgPolicyScriptService) Unregisters the OrgPolicyScriptService for the designated script type from this policy resolution.

Method Detail

checkSyntax

OrgPolicyReport checkSyntax(java.lang.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,
                                   java.lang.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

java.util.Set<QualifiedAgent> resolvePolicy(SessionToken session,
                                            java.lang.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<java.util.List<QualifiedAgent>> resolvePolicyIterator(SessionToken session,
                                                                     java.lang.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

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,
                 java.lang.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

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,
                 java.lang.String agentUserName,
                 java.lang.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

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,
                 java.lang.String agentUserName,
                 java.lang.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

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

java.util.List<java.net.URI[]> registerOrgPolicyScriptService(SessionToken session,
                                                              java.lang.String scriptType,
                                                              java.net.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.
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 existing 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. 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

java.util.List<java.net.URI[]> unregisterOrgPolicyScriptService(SessionToken session,
                                                                java.lang.String scriptType,
                                                                java.net.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. If this method call unregisters the designated script type completely, an empty list will be returned. If the designated script type is not registered, null will be returned.

registerOrgPolicyHandler

boolean registerOrgPolicyHandler(SessionToken session,
                                 java.lang.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,
                                   java.lang.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).