com.microsoft.tfs.core.checkinpolicies
Class PolicyEvaluator

java.lang.Object
  extended by com.microsoft.tfs.core.checkinpolicies.PolicyEvaluator
All Implemented Interfaces:
com.microsoft.tfs.util.Closable

public class PolicyEvaluator
extends java.lang.Object
implements com.microsoft.tfs.util.Closable

A long-lived object that manages evaluation of check-in policies. Most UI controls will use a PolicyEvaluator to drive policy evaluation (and user-initiated re-evaluation). Clients like the command-line client will use one (for a short time) for evaluation.

After a PolicyEvaluator is constructed, it is initialized with a pending checkin via setPendingCheckin(PendingCheckin).

Then, evaluation is done via the public evaluate(PolicyContext) method, or reloadAndEvaluate(PolicyContext) if the policy definitions and implementations should be re-loaded from the server. Policy failures can be retrieved after evaluation with getFailures(), or by attaching listeners with addPolicyStateChangedListener(PolicyStateChangedListener).

The general status of the object can be watched through events ( addPolicyEvaluatorStateChangedListener(PolicyEvaluatorStateChangedListener) ) or with getPolicyEvaluatorState(). See PolicyEvaluatorState for information on possible states.

A new pending check-in can be assigned at any time with setPendingCheckin(PendingCheckin). The evaluator resets its state, and is ready to evaluate again.

Call the close() method when done with the evaluator, so it can close its policy implementations (which may have large objects to release or events to unhook).

Context Notes

Callers don't need to supply a TaskMonitor in the policy context they pass to reloadAndEvaluate(PolicyContext) or evaluate(PolicyContext). The PolicyEvaluator will put one in the context when it runs the policy instances.

Handling Load Errors

The evaluator doesn't normally throw exceptions during evaluate(PolicyContext) or reloadAndEvaluate(PolicyContext) if a configured policy could not be loaded from disk. Instead, the evaluator's state is set to PolicyEvaluatorState.POLICIES_LOAD_ERROR and the caller can test for this state with getPolicyEvaluatorState(). If the caller is interested in the load error details (including exception data), it can register an event listener via addPolicyLoadErrorListener(PolicyLoadErrorListener) which is fired as the load error happens.

See Also:
PolicyEvaluatorState
Since:
TEE-SDK-10.1
Thread-safety:
thread-safe

Constructor Summary
PolicyEvaluator(VersionControlClient client, PolicyLoader policyLoader)
          Builds a policy evaluator for the given VersionControlClient.
 
Method Summary
 void addPolicyEvaluatorStateChangedListener(PolicyEvaluatorStateChangedListener listener)
          Add a listener for the event fired when the state of this evaluator changes (perhaps because it has been given a new pending checkin or team project to run policies for).
 void addPolicyLoadErrorListener(PolicyLoadErrorListener listener)
          Adds a listener for the PolicyLoadErrorEvent, which is fired when a policy implementation fails to load during an evaluate(PolicyContext) or reloadAndEvaluate(PolicyContext) call.
 void addPolicyStateChangedListener(PolicyStateChangedListener listener)
           
 void close()
          
 PolicyFailure[] evaluate(PolicyContext policyContext)
          Evaluates checkin policies.
 PolicyFailure[] getFailures()
           
 PendingCheckin getPendingCheckin()
           
 int getPolicyCount()
           
 PolicyEvaluatorState getPolicyEvaluatorState()
           
 PolicyLoader getPolicyLoader()
           
static java.lang.String makeTextErrorForLoadException(java.lang.Throwable throwable)
          Returns a text error message (with newlines) suitable for printing in a console window, log file, or other text area that describes a problem loading a check-in policy implementation so the user can fix the problem.
 PolicyFailure[] reloadAndEvaluate(PolicyContext policyContext)
          Reloads all policy definitions from the server and evaluates all policies via evaluate(PolicyContext).
 void removePolicyEvaluatorStateChangedListener(PolicyEvaluatorStateChangedListener listener)
          Remove a listener for the event fired when the state of this evaluator changes (perhaps because it has been given a new pending checkin or team project to run policies for).
 void removePolicyLoadErrorListener(PolicyLoadErrorListener listener)
          Removes a listener for the PolicyLoadErrorEvent, which is fired when a policy implementation fails to load during an evaluate(PolicyContext) or reloadAndEvaluate(PolicyContext) call.
 void removePolicyStateChangedListener(PolicyStateChangedListener listener)
           
 void setPendingCheckin(PendingCheckin pendingCheckin)
          Sets the pending checkin used for policy evaluations.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PolicyEvaluator

public PolicyEvaluator(VersionControlClient client,
                       PolicyLoader policyLoader)
Builds a policy evaluator for the given VersionControlClient. No checkin policies are automatically loaded or evaluated during construction.

Method Detail

addPolicyEvaluatorStateChangedListener

public void addPolicyEvaluatorStateChangedListener(PolicyEvaluatorStateChangedListener listener)
Add a listener for the event fired when the state of this evaluator changes (perhaps because it has been given a new pending checkin or team project to run policies for).

Parameters:
listener - the listener to add (must not be null)

removePolicyEvaluatorStateChangedListener

public void removePolicyEvaluatorStateChangedListener(PolicyEvaluatorStateChangedListener listener)
Remove a listener for the event fired when the state of this evaluator changes (perhaps because it has been given a new pending checkin or team project to run policies for).

Parameters:
listener - the listener to remove (must not be null)

addPolicyStateChangedListener

public void addPolicyStateChangedListener(PolicyStateChangedListener listener)
See Also:
PolicyInstance.addPolicyStateChangedListener(PolicyStateChangedListener)

removePolicyStateChangedListener

public void removePolicyStateChangedListener(PolicyStateChangedListener listener)
See Also:
PolicyInstance.removePolicyStateChangedListener(PolicyStateChangedListener)

addPolicyLoadErrorListener

public void addPolicyLoadErrorListener(PolicyLoadErrorListener listener)
Adds a listener for the PolicyLoadErrorEvent, which is fired when a policy implementation fails to load during an evaluate(PolicyContext) or reloadAndEvaluate(PolicyContext) call.

Parameters:
listener - the listener to add (must not be null)

removePolicyLoadErrorListener

public void removePolicyLoadErrorListener(PolicyLoadErrorListener listener)
Removes a listener for the PolicyLoadErrorEvent, which is fired when a policy implementation fails to load during an evaluate(PolicyContext) or reloadAndEvaluate(PolicyContext) call.

Parameters:
listener - the listener to remove (must not be null)

setPendingCheckin

public void setPendingCheckin(PendingCheckin pendingCheckin)
Sets the pending checkin used for policy evaluations. Resets the state of the evaluator to PolicyEvaluatorState.UNEVALUATED.

Parameters:
pendingCheckin - the pending checkin used for policy evaluations (must not be null)

reloadAndEvaluate

public PolicyFailure[] reloadAndEvaluate(PolicyContext policyContext)
                                  throws PolicyEvaluationCancelledException
Reloads all policy definitions from the server and evaluates all policies via evaluate(PolicyContext).

Returns:
the value returned by evaluate(PolicyContext);
Throws:
PolicyEvaluationCancelledException - if the user cancelled the policy evaluation.

close

public void close()

Specified by:
close in interface com.microsoft.tfs.util.Closable

evaluate

public PolicyFailure[] evaluate(PolicyContext policyContext)
                         throws PolicyEvaluationCancelledException
Evaluates checkin policies.

Parameters:
policyContext - contextual settings that may include information about the user interface, etc. (must not be null)
Returns:
any failures detected.
Throws:
PolicyEvaluationCancelledException - if the user canceled the policy evaluation.

getPolicyEvaluatorState

public PolicyEvaluatorState getPolicyEvaluatorState()
Returns:
the current state of this evaluator

getPolicyCount

public int getPolicyCount()
Returns:
the count of policy definitions loaded. Can be 0 if loadPolicies(PolicyContext) and setPendingCheckin(PendingCheckin) were not called, or if no policies were defined or loaded for the current pending checkin.

getFailures

public PolicyFailure[] getFailures()
Returns:
shallow copy of all the failures from all the policies evaluated by this evaluator. Do not modify the objects returned.

getPolicyLoader

public PolicyLoader getPolicyLoader()
Returns:
the PolicyLoader in use by this evaluator.

getPendingCheckin

public PendingCheckin getPendingCheckin()
Returns:
the pending checkin that was previously set via setPendingCheckin(PendingCheckin).

makeTextErrorForLoadException

public static java.lang.String makeTextErrorForLoadException(java.lang.Throwable throwable)
Returns a text error message (with newlines) suitable for printing in a console window, log file, or other text area that describes a problem loading a check-in policy implementation so the user can fix the problem. Things like policy type ID, installation instructions, and sometimes stack traces are formatted into the message.

Parameters:
throwable - the problem that caused the load failure, usually these are PolicyLoaderException, but they can be any kind of Throwable and the error message will be as descriptive as possible (must not be null)
Returns:
the formatted error text.


© 2015 Microsoft. All rights reserved.