com.microsoft.tfs.core.checkinpolicies
Interface PolicyInstance

All Superinterfaces:
com.microsoft.tfs.util.Closable
All Known Implementing Classes:
PolicyBase

public interface PolicyInstance
extends com.microsoft.tfs.util.Closable

An instance is a loaded, configured, configurable, and evaluatable policy object ready for use by the framework. Objects that implement this interface are loaded by the framework (see PolicyLoader) and included in lists of available policies. They may also be configured and evaluated directly from UI code.

See PolicyBase for a ready-to-extend class that implements much of this interface.

Cancellation

Policies that take a long time to run should support cancellation. In your evaluate(PolicyContext) implementation, get a TaskMonitor instance from the PolicyContext, using the key defined at PolicyContextKeys.TASK_MONITOR. If the context returns a non-null TaskMonitor, simply test whether the user wishes to cancel via TaskMonitor.isCanceled() method. If this method returns true, simply throw PolicyEvaluationCancelledException to cancel all policy evaluation.

The context may return a null value for the PolicyContextKeys.TASK_MONITOR key if the environment hosting the policy framework did not set a task monitor.

Most policies that complete quickly do not need to support cancellation via TaskMonitor. Its use is never required.

Progress Reporting

Implementations can use the same mechanism for cancellation to report progress: TaskMonitor. When an implementation wants to use a TaskMonitor to report on its progress, it must call TaskMonitor.begin(String, int) before calling TaskMonitor.worked(int) or TaskMonitor.setCurrentWorkDescription(String), then it must call TaskMonitor.done().

Most policies that complete quickly do not need to interact with a TaskMonitor object. Its use is never required.

Good UI Behavior

When running in a graphical environment (like Eclipse), the policy framework may invoke evaluate(PolicyContext) on a background thread. This allows the user interface to update itself (paint) while a policy evalutes (possibly taking several seconds or even minutes). See the Javadoc on evaluate(PolicyContext) for thread marshalling requirements. Multiple policies defined on the same team project will never run concurrently, and the environment will always wait until all policies complete before allowing a check-in to proceed.

Because of this threading design, implementations are not required to manually service the user interface's event loop, and may perform long computations directly inside evaluate(PolicyContext).

Thread Policy

Implementations of this class should be fully synchronized to ensure re-entrancy and data visibility. The framework does not schedule calls into an implementation from multiple threads simultaneously, but events fired during an policy's evaluation may cause other threads in the environment (i.e. Eclipse) to read data from the implementation to update status information. These calls require synchronization in the implementation.

The policy framework may call constructors, initialize(PendingCheckin, PolicyContext), and evaluate(PolicyContext) on different threads for a single instance of this class. For this reason, implementations should not store thread-local information in these methods to be used by other methods.

See Also:
PolicyBase
Since:
TEE-SDK-10.1
Thread-safety:
thread-compatible

Method Summary
 void activate(PolicyFailure failure, PolicyContext context)
           Called when the user activates (by double-clicking or some other user interface) a failure generated by a previous call to evaluate(PolicyContext).
 void addPolicyStateChangedListener(PolicyStateChangedListener listener)
          Adds a policy state changed listener that receives a PolicyStateChangedEvent whenever this policy is evaluated and a new set of failures is generated.
 boolean canEdit()
           
 void displayHelp(PolicyFailure failure, PolicyContext context)
           Shows help about the given failure if it was selected for help in the user interface.
 boolean edit(PolicyEditArgs policyEditArgs)
           Edits the policy's configuration by interacting with the graphical user interface, if appropriate, or by other means.
 PolicyFailure[] evaluate(PolicyContext context)
           Evaluates the pending checkin for policy compliance and returns any failures encountered.
 PolicyType getPolicyType()
           
 void initialize(PendingCheckin pendingCheckin, PolicyContext context)
           Prepares a PolicyInstance for policy evaluation.
 void loadConfiguration(Memento configurationMemento)
           Loads run-time configuration information from the given Memento, which was previously build by a call to saveConfiguration(Memento).
 void removePolicyStateChangedListener(PolicyStateChangedListener listener)
          Removes a policy state changed listener that was previously added via addPolicyStateChangedListener(PolicyStateChangedListener).
 void saveConfiguration(Memento confgurationMemento)
           Saves the run-time configuration of this instance to the given (empty except for name) Memento object, which will be persisted by the framework in the policy definition in the Team Foundation Server.
 
Methods inherited from interface com.microsoft.tfs.util.Closable
close
 

Method Detail

getPolicyType

PolicyType getPolicyType()
Returns:
the PolicyType information for this instance.

canEdit

boolean canEdit()
Returns:
true if this policy's run-time configuration can be edited, false if editing should be disallowed by the user interface.

edit

boolean edit(PolicyEditArgs policyEditArgs)

Edits the policy's configuration by interacting with the graphical user interface, if appropriate, or by other means. Implementations should obtain references to user interface objects from the PolicyEditArgs map. This object's configuration is later retrieved by the framework (via saveConfiguration(Memento)) and saved in the policy definition on the Team Foundation Server.

The policy framework will always invoke this method from the UI thread when running in Eclipse and Explorer.

Thread Policy

The policy framework always invokes this method on the user-interface thread, if the graphical environment where the framework is hosted requires it. Implementations may use the graphical interface context objects directly, without marhsalling calls to the UI thread.

Parameters:
policyEditArgs - a map of strings to objects that can be used as context for interface building.
Returns:
true if the user made changes to this policy's configuration, false if the edit operation was cancelled and no changes were made.

saveConfiguration

void saveConfiguration(Memento confgurationMemento)

Saves the run-time configuration of this instance to the given (empty except for name) Memento object, which will be persisted by the framework in the policy definition in the Team Foundation Server.

Implementations should not perform user interface work in this method.

Memento Notes

Implementations should not store text data directly inside the given memento node (via Memento.putTextData(String), but instead they should create child nodes to store text data. Any text data stored on the given node will be discarded when it is saved. Implementations are encouraged to set other types of attributes (Integer, String, Boolean, etc.) directly on the given node or any child nodes they create.

Parameters:
confgurationMemento - the empty (except for name) Memento to save settings to (must not be null)

loadConfiguration

void loadConfiguration(Memento configurationMemento)

Loads run-time configuration information from the given Memento, which was previously build by a call to saveConfiguration(Memento).

Implementations should not perform user interface work in this method.

Parameters:
configurationMemento - the Memento to load settings from (must not be null)

addPolicyStateChangedListener

void addPolicyStateChangedListener(PolicyStateChangedListener listener)
Adds a policy state changed listener that receives a PolicyStateChangedEvent whenever this policy is evaluated and a new set of failures is generated.

Policies being evaluated in a graphical context (in an application like the Plug-in for Eclipse, or Explorer) can fire this event to cause the graphical display of their state (including failures) to be updated.

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

removePolicyStateChangedListener

void removePolicyStateChangedListener(PolicyStateChangedListener listener)
Removes a policy state changed listener that was previously added via addPolicyStateChangedListener(PolicyStateChangedListener). changes.

Parameters:
listener - the listener to remove (must not be null)
See Also:
addPolicyStateChangedListener(PolicyStateChangedListener)

initialize

void initialize(PendingCheckin pendingCheckin,
                PolicyContext context)

Prepares a PolicyInstance for policy evaluation. The framework tries to keep PolicyInstance instances around as long as possible, for performance reasons, so it will invoke this method repeatedly to re-configure the object for a new pending checkin.

If you allocate resources in this method, Closable.close() is a good place to release them.

Implementations should not save the PolicyContext object for later use, because the framework may pass a different context to evaluate(PolicyContext).

Implementations should not perform user interface work in this method because the framework tries to initialize a policy as lazily as it can, but also must call initialize many times as the checkin data changes.

Parameters:
pendingCheckin - the pending changes that will be evaluated by this PolicyInstance (must not be null)
context - contextual settings that may include information about the user interface, etc. (must not be null)

evaluate

PolicyFailure[] evaluate(PolicyContext context)
                         throws PolicyEvaluationCancelledException

Evaluates the pending checkin for policy compliance and returns any failures encountered. Called by the checkin policy framework at various times during the life of the PolicyInstance object, but always after initialize(PendingCheckin, PolicyContext) was called with a pending checkin and contextual information.

Implementations should not save the PolicyContext object for later use, becuase the objects inside it are not guaranteed to persist after evaluate(PolicyContext) returns. This restriction means that policies which call their own evaluate(PolicyContext) method (as a result of an external event or some other design decision) must create their own PolicyContext instances for this call. They can re-use the values from the original, framework-called evaluate(PolicyContext) at their own risk--these objects may become stale or invalid.

Thread Policy

Implementations must not assume this method will be invoked on any specific thread. More specifically, if the framework is running in an application with a graphical user interface, any user-interface work done in the policy (through objects obtained in the context, for example) must be marshalled to the correct thread, if required by the interface toolkit in use. For Eclipse plug-ins, this means access to all user-interface objects should be done by by org.eclipse.swt.widgets.Display's asyncExec(Runnable) or syncExec(Runnable) methods.

Parameters:
context - contextual settings that may include information about the user interface, etc. (must not be null)
Returns:
any failures encounterd by this policy, or an empty PolicyFailure array if none encountered.
Throws:
PolicyEvaluationCancelledException - if the user cancelled the policy evaluation.

activate

void activate(PolicyFailure failure,
              PolicyContext context)

Called when the user activates (by double-clicking or some other user interface) a failure generated by a previous call to evaluate(PolicyContext). Implementations should further explain the failure, perhaps presenting additional information or proposing a solution.

Always called after the framework has called initialize(PendingCheckin, PolicyContext).

Thread Policy

The policy framework always invokes this method on the user-interface thread, if the graphical environment where the framework is hosted requires it. Implementations may use the graphical interface context objects directly, without marhsalling calls to the UI thread.

Parameters:
failure - the failure to activate or display (must not be null)
context - contextual settings that may include information about the user interface, etc. (must not be null)

displayHelp

void displayHelp(PolicyFailure failure,
                 PolicyContext context)

Shows help about the given failure if it was selected for help in the user interface.

Always called after the framework has called initialize(PendingCheckin, PolicyContext).

Thread Policy

The policy framework always invokes this method on the user-interface thread, if the graphical environment where the framework is hosted requires it. Implementations may use the graphical interface context objects directly, without marhsalling calls to the UI thread.

Parameters:
failure - the failure to display help for (must not be null)
context - contextual settings that may include information about the user interface, etc. (must not be null)


© 2015 Microsoft. All rights reserved.