|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface PolicyInstance
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.
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.
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.
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)
.
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.
PolicyBase
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 |
---|
PolicyType getPolicyType()
PolicyType
information for this instance.boolean canEdit()
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.
policyEditArgs
- a map of strings to objects that can be used as context for
interface building.
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.
confgurationMemento
- the empty (except for name) Memento
to save settings to
(must not be null
)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.
configurationMemento
- the Memento
to load settings from (must not be
null
)void addPolicyStateChangedListener(PolicyStateChangedListener listener)
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.
listener
- the listener to add (must not be null
)void removePolicyStateChangedListener(PolicyStateChangedListener listener)
addPolicyStateChangedListener(PolicyStateChangedListener)
.
changes.
listener
- the listener to remove (must not be null
)addPolicyStateChangedListener(PolicyStateChangedListener)
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.
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
)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.
context
- contextual settings that may include information about the user
interface, etc. (must not be null
)
PolicyFailure
array if none encountered.
PolicyEvaluationCancelledException
- if the user cancelled the policy evaluation.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.
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
)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.
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
)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |