wt.projmgmt.monitor
Interface ProjMonitorService

All Known Implementing Classes:

ProjMonitorServiceFwd, StandardProjMonitorService

public interface ProjMonitorService

The StandardProjMonitorService class contains the standard implementation of both remotely and server accessible API.

This service is a light-weight service and depends on the wt.projmgmt.StandardProjMgmtService for dispatching and capturing events.

Supported API: true

Extendable: false

See Also:

ProjMonitorService, wt.projmgmt.monitor.ProjMonitorServicSvr, ProjMgmtService

Method Summary

ExecutionObject	addDeliverable(ExecutionObject exec_obj, Deliverable deliverable) Adds Deliverable to ExecutionObject.
ExecutionObject	changeActualFinish(ExecutionObject exec_obj, Timestamp actual_finish) Changes the actual finish time for ExecutionObject objects to the time passed as argument.
ExecutionObject	changeActualStart(ExecutionObject exec_obj, Timestamp actual_start) Changes the actual start time for t.projmgmt.execution.ExecutionObject objects to the time passed as argument.
ExecutionObject	changeCompletionTime(ExecutionObject exec_obj, Timestamp new_time) Changes the completion time of the wt.projmgtm.execution.ExecutionObject to the time passed as argument.
ExecutionObject	changeCost(ExecutionObject exec_obj, Currency new_total_cost, Currency new_curr_cost) Changes the total and current costs of the execution object passed as argument.
ExecutionObject	changeDeadline(ExecutionObject exec_obj, Timestamp new_deadline) Changes deadline of the ExecutionObject passed as argument.
ExecutionObject	changeDuration(ExecutionObject exec_obj, TimeToElapse new_duration) Changes the duration of the ExecutionObject passed as argument.
ExecutionObject	changeEstimatedFinish(ExecutionObject exec_obj, Timestamp new_finish) Changes expected finish date for the ExecutionObject.
ExecutionObject	changeExecutionState(ExecutionObject exec_obj, ProjectState new_state) Changes execution state of the ExecutionObject passed as argument.
ExecutionObject	changeMonitorInfo(ExecutionObject exec_obj, MonitorInfo new_info) Changes dynamic information associated with the ExecutionObject passed as argument.
ExecutionObject	changeOwner(ExecutionObject exec_obj, WTPrincipal new_owner) Changes the owner of the ExecutionObject passed as argument.
ExecutionObject	changePercentComplete(ExecutionObject exec_obj, int new_percent, Work total_work) Changes the percent complete the ExecutionObject passed as argument.
ExecutionObject	changeRollUpDeliverables(ExecutionObject exec_obj, boolean roll_up) Changes the roll up deliverables flag in the ExecutionObject passed as argument.
ExecutionObject	changeStatus(ExecutionObject exec_obj, ProjectHealthStatus new_status, String desc) Changes health status (ProjectHealthStatus of execution object passed as argument.
ExecutionObject	changeTimePastDeadline(ExecutionObject exec_obj, TimeToElapse new_time) Changes the time interval past deadline of the ExecutionObject passed as argument.
ExecutionObject	changeTimeToDeadline(ExecutionObject exec_obj, TimeToElapse new_time) Changes the time interval to deadline of the ExecutionObject passed as argument.
ExecutionObject	changeTimeToStart(ExecutionObject exec_obj, Timestamp new_start) Changes the time to start of an ExecutionObject to the time passed as argument.
void	completeWorkItem(ProjectWorkItem work_item, WTPrincipalReference p_ref, Vector events) Completes the ProjectWorkItem passed as argument.
QueryResult	getProjectHistory(ProjectPlan plan, Vector source_objects, Vector event_types) Deprecated.
QueryResult	getProjectSubscriptions(ProjectPlan plan, WTUser user) Returns all ObjectSubscription associated with the project and user passed as arguments.
MonitorInfo	getRolledUpValues(ExecutionObject exec_obj) Returns dynamic values from contained objects.
Enumeration	getSubscribers(ExecutionObject exec_obj, ProjectEventType event) Get all subscribers for an event for the ExecutionObject passed as argument.
QueryResult	getSubscriptions(ExecutionObject exec_obj, WTUser user) Returns all ObjectSubscription directly associated with the ExecutionObject and the WTUser passed as arguments.
boolean	isManager(ProjectPlan plan, WTUser user) Returns 'true' if a wt.or.WTUser is a manager of the project that owns the ProjectPlan passed as argument.
DeliverableHolder	removeDeliverable(DeliverableHolder holder, Deliverable deliverable) Removes deliverable to execution object.
ExecutionObject	rollUpValues(ExecutionObject exec_obj) Computes and sets dynamic values of the execution object.
ExecutionObject	rollUpValues(ExecutionObject exec_obj, ExecutionConfiguration roll_up_attrs) Computes and sets dynamic values of the execution object.
void	subscribe(ExecutionObject exec_obj, ProjectEventType event, Vector subscribers, String msg) Create ObjectSubscription objects for an event for a given object.
void	subscribe(ExecutionObject exec_obj, ProjectEventType event, Vector subscribers, String msg, String attr_name, String attr_value, String key) Create ObjectSubscription objects for an event for a given object.
void	unsubscribe(ExecutionObject exec_obj, ProjectEventType event, Vector subscribers) Delete ObjectSubscription for an event and a given object.
void	unsubscribe(ExecutionObject exec_obj, ProjectEventType event, Vector subscribers, String msg, String attr_name, String attr_value, String key) Create ObjectSubscription objects for an event for a given object.

Method Detail

addDeliverable

public ExecutionObject addDeliverable(ExecutionObject exec_obj,
                                      Deliverable deliverable)
                               throws WTException

Adds Deliverable to ExecutionObject. A deliverable can belong to at most one ProjectActivity, so if the execution object is an activity and the deliverable already belongs to an activity, the deliverable owner is replaced. Propagates deliverable status, if necessary.

Supported API: true

Parameters:

exec_obj -

deliverable -

Returns:

ExecutionObject

Throws:

WTException

changeActualFinish

public ExecutionObject changeActualFinish(ExecutionObject exec_obj,
                                          Timestamp actual_finish)
                                   throws WTException

Changes the actual finish time for ExecutionObject objects to the time passed as argument. The new actual time is aligned before it is set. The ability to set actual finish is supported only for the manual execution mode. If the mode is not manual, then an exception is thrown. This operation is restricted to the owner of the object or the project manager. An authorization exception is thrown if this is nt the case. Changing the finish time of an object is propagated to all objects whose schedule depend on the modified object and have not started yet. If a following, dependent object has already started, then the start and finish dates for that dependent activity are not adjusted.

Completing objects

If the object has not completed, providing a non-null time has the effect of completing it. As a consequence, the % complete is automatically set to 100%.

Supported API: false

Parameters:

exec_obj -

actual_finish -

Returns:

ExecutionObject

Throws:

WTException

changeActualStart

public ExecutionObject changeActualStart(ExecutionObject exec_obj,
                                         Timestamp actual_start)
                                  throws WTException

Changes the actual start time for t.projmgmt.execution.ExecutionObject objects to the time passed as argument. The new actual time is aligned before it is set. The ability to set actual start is supported only for the manual execution mode. If the mode is not manual, then an exception is thrown. This operation is restricted to the owner of the object or the project manager. An uthorization exception is thrown if this is not the case. For objects that are not completed, the estimated finish is updated based on the object's duration. This new finish is propagated to all dependent objects that have not started yet. If a following, dependent object has already started, then the start and finish dates for that dependent activity are not adjusted. Changing the actual start for completed objects changes does not change the actual finish. An exception is thrown when the user attempts to change the actual start to a time after the actual finish.

Starting objects

If the object has not started, providing a non-null start time has the effect of starting it, even though the % complete may be greater than zero.

Unstarting objects

If the time passed as argument is 'null' the object changes to a 'non-started' state ("unstarted").This has the following side-effects: % complete, status and other dynamic information are reset and actual finish is reset (for completed objects).

Supported API: false

Parameters:

exec_obj -

actual_start -

Returns:

ExecutionObject

Throws:

WTException

changeCompletionTime

public ExecutionObject changeCompletionTime(ExecutionObject exec_obj,
                                            Timestamp new_time)
                                     throws WTException

Changes the completion time of the wt.projmgtm.execution.ExecutionObject to the time passed as argument. A ProjectManagementException is thrown in the following cases.

• If the object is not closed (that is completed or cancelled).
• If the new completion time is prior to the start time.
• If the given time is later than the current end time

Notes:

• Requires manager privileges: exception thrown if user is not a manager.
• The new time is not propagated to dependent nodes or to the containers of the object.

Supported API: true

Parameters:

exec_obj -

new_time -

Returns:

ExecutionObject

Throws:

WTException

See Also:

wt.projmgmt.ProjectState

changeCost

public ExecutionObject changeCost(ExecutionObject exec_obj,
                                  Currency new_total_cost,
                                  Currency new_curr_cost)
                           throws WTException

Changes the total and current costs of the execution object passed as argument. The cost change is propagated to all other execution objects that depend on the one passed as argument. NoteThese costs are only work costs; they don't include costs derived from resources other than person resources.

Supported API: true

Parameters:

exec_obj -

new_total_cost -

new_curr_cost -

Returns:

ExecutionObject

Throws:

WTException

changeDeadline

public ExecutionObject changeDeadline(ExecutionObject exec_obj,
                                      Timestamp new_deadline)
                               throws WTException

Changes deadline of the ExecutionObject passed as argument. The deadline is propagated to contained objects as an "inherited deadline." Schedules a DEADLINE event to be generated at the deadline if the object is still running at this time. If there are subscribers to this event and to this object, they will receive notification that the deadline has passed.

Supported API: true

Parameters:

exec_obj -

new_deadline -

Returns:

ExecutionObject

Throws:

WTException

changeDuration

public ExecutionObject changeDuration(ExecutionObject exec_obj,
                                      TimeToElapse new_duration)
                               throws WTException

Changes the duration of the ExecutionObject passed as argument. As a consequence of this operation, the estimated finished time of the object is updated and set to "overriden." Propagates scheduling changes to holder objects.

Supported API: true

Parameters:

exec_obj -

new_duration -

Returns:

ExecutionObject

Throws:

WTException

changeEstimatedFinish

public ExecutionObject changeEstimatedFinish(ExecutionObject exec_obj,
                                             Timestamp new_finish)
                                      throws WTException

Changes expected finish date for the ExecutionObject. As a consequence of this operation, the duration of the object is updated and set to "overriden." Propagates scheduling changes to holder objects.

Supported API: true

Parameters:

exec_obj -

new_finish -

Returns:

ExecutionObject

Throws:

WTException

changeExecutionState

public ExecutionObject changeExecutionState(ExecutionObject exec_obj,
                                            ProjectState new_state)
                                     throws WTException

Changes execution state of the ExecutionObject passed as argument. Changing the execution state of objects may cause scheduling and other changes. For example, starting may change the estimated finish; completing sets % complete to 100. These changes are propagated to nodes in the plan that are dependent on the node that changed state.

Supported API: true

Parameters:

exec_obj -

new_state -

Returns:

ExecutionObject

Throws:

WTException

changeMonitorInfo

public ExecutionObject changeMonitorInfo(ExecutionObject exec_obj,
                                         MonitorInfo new_info)
                                  throws WTException

Changes dynamic information associated with the ExecutionObject passed as argument. This dynamic information is contained in a MonitorInfo object and consists of status (ProjectHealthStatus), percent complete, estimated finish date, performed work, and total work. The advantage of using this API over updating each piece of information separately is that all the information is propagated together, reducing the number of propagation threads.

Supported API: true

Parameters:

exec_obj -

new_info -

Returns:

ExecutionObject

Throws:

WTException

changeOwner

public ExecutionObject changeOwner(ExecutionObject exec_obj,
                                   WTPrincipal new_owner)
                            throws WTException

Changes the owner of the ExecutionObject passed as argument. Existing owner subscriptions are transferred to new owner.

Supported API: true

Parameters:

exec_obj -

new_owner -

Returns:

ExecutionObject

Throws:

WTException

changePercentComplete

public ExecutionObject changePercentComplete(ExecutionObject exec_obj,
                                             int new_percent,
                                             Work total_work)
                                      throws WTException

Changes the percent complete the ExecutionObject passed as argument. If the final percent is 100%, this causes the object to change to the COMPLETED state. The percent change is propagated to all other execution objects that depend on the one passed as argument.

The percent complete of an execution object is related to the performed and total work through the formula (class invariant): percentComplete = performedWork / totalWork Also the performed work can't be greater than the total work.

 performedWork <= totalWork
 

This means that changing the percent complete necessarily changes the performed work. In case the total work is zero, performed work is necessarily also zero. In this case the convention is to set percent complete to 100. Note also that when propagating percent complete, to holder objects it is the performed work and total work that are actually propagated.

Supported API: true

Parameters:

exec_obj -

new_percent -

total_work -

Returns:

ExecutionObject

Throws:

WTException

changeRollUpDeliverables

public ExecutionObject changeRollUpDeliverables(ExecutionObject exec_obj,
                                                boolean roll_up)
                                         throws WTException

Changes the roll up deliverables flag in the ExecutionObject passed as argument. If the flag is set to 'true' then the dynamic values of the plan are obtained from the deliverables rather than from the activities. Although one can pass an execution object as argument, it is preferable to pass a ProjectPlan. Otherwise one may get inconsistent values throughout the plan. NoteOnly the dynamic values that are not overridden are actually rolled up.

Supported API: true

Parameters:

exec_obj -

roll_up -

Returns:

ExecutionObject

Throws:

WTException

changeStatus

public ExecutionObject changeStatus(ExecutionObject exec_obj,
                                    ProjectHealthStatus new_status,
                                    String desc)
                             throws WTException

Changes health status (ProjectHealthStatus of execution object passed as argument. A status description can be optionally provided. The status change is propagated to all other execution objects that depend on the one passed as argument whose status values are not overridden.

Supported API: true

Parameters:

exec_obj -

new_status -

desc -

Returns:

ExecutionObject

Throws:

WTException

changeTimePastDeadline

public ExecutionObject changeTimePastDeadline(ExecutionObject exec_obj,
                                              TimeToElapse new_time)
                                       throws WTException

Changes the time interval past deadline of the ExecutionObject passed as argument. Schedules a TIME_PAST_DEADLINE event to be generated at a time equals to deadline + new_time if the object is still running at this time. If there are subscribers to this event and to this object, they will receive notification that the deadline has passed.

Supported API: true

Parameters:

exec_obj -

new_time -

Returns:

ExecutionObject

Throws:

WTException

changeTimeToDeadline

public ExecutionObject changeTimeToDeadline(ExecutionObject exec_obj,
                                            TimeToElapse new_time)
                                     throws WTException

Changes the time interval to deadline of the ExecutionObject passed as argument. Schedules a TIME_TO_DEADLINE event to be generated at a time equals to deadline - new_time if the object is still running at this time. If there are subscribers to this event and to this object, they will receive notification that the deadline is approaching.

Supported API: true

Parameters:

exec_obj -

new_time -

Returns:

ExecutionObject

Throws:

WTException

changeTimeToStart

public ExecutionObject changeTimeToStart(ExecutionObject exec_obj,
                                         Timestamp new_start)
                                  throws WTException

Changes the time to start of an ExecutionObject to the time passed as argument. If the time passed as argument is 'null' the time is set to the earliest possible date.

The state of the object must be ProjectState.DEFINED (that is, not started yet) otherwise an exception is thrown.

Also an exception is thrown if a date constraint is violated (for example, start the object before the time a predecessor node finishes).

As a consequence of this method, if the time is not null, the "start computed" flag is set to 'false' indicating that the time to start is explicitly set. Otherwise it is set to 'true'.

The new start time is propagated to the container of the object if there are no predecessors that belong to the same container. Also new estimated finish is computed and propagated to successor nodes and to the container if there are no successor nodes that belong to the same container.

Note:This method doesn't apply to deliverables and project work items.

Supported API: true

Parameters:

exec_obj -

new_start -

Returns:

ExecutionObject

Throws:

WTException

See Also:

ProjectState, ExecutionObject, ProjectNode

completeWorkItem

public void completeWorkItem(ProjectWorkItem work_item,
                             WTPrincipalReference p_ref,
                             Vector events)
                      throws WTException

Completes the ProjectWorkItem passed as argument. The user assigned to the work item and a list of events should be passed as well. For project management the list should be empty. Percent complete is set to 100 and this and other dynamic values are propagated to the ProjectActivity that holds the item.

Supported API: true

Parameters:

work_item -

p_ref -

events -

Throws:

WTException

getProjectHistory

public QueryResult getProjectHistory(ProjectPlan plan,
                                     Vector source_objects,
                                     Vector event_types)
                              throws WTException

Deprecated.

Returns all events associated with a given plan and source objects that are of the types given in the 'event_types' Vector. If the execution object vector passed as argument is null, events for all objects of the plan are returned. If the 'event_types' Vector is null, all events are returned. Whatever is the option chosen, the events are returned in the order they occurred. The project plan argument is only considered when the execution object is null. NoteOnly recorded events are retrieved. Which events are recorded is controlled through properties definable in wt.properties. The properties are the following and should be set to "true" for the ones that should be recorded.

• "wt.projmgmt.recordStateChange"
• "wt.projmgmt.recordStatusChange"
• "wt.projmgmt.recordPercentChange"
• "wt.projmgmt.recordFinishChange"
• "wt.projmgmt.recordDeadlineChange"
• "wt.projmgmt.recordObjectDeletion"
• "wt.projmgmt.recordMissedDeadline"
• "wt.projmgmt.recordApproachingDeadline"
• "wt.projmgmt.recordPastDeadline"
• "wt.projmgmt.recordOwnerChange"

Parameters:

plan -

source_objects -

event_types -

Returns:

QueryResult

Throws:

WTException

getProjectSubscriptions

public QueryResult getProjectSubscriptions(ProjectPlan plan,
                                           WTUser user)
                                    throws WTException

Returns all ObjectSubscription associated with the project and user passed as arguments. The subscriptions may be associated directly with the plan or to one of its contained nodes (ProjectNode). If user is 'null' all plan subscriptions are returned.

Supported API: true

Parameters:

plan -

user -

Returns:

QueryResult

Throws:

WTException

getRolledUpValues

public MonitorInfo getRolledUpValues(ExecutionObject exec_obj)
                              throws WTException

Returns dynamic values from contained objects. These values are the health status, percent complete, estimated finish time, and total work. For example, if the passed object is a project activity, returns the values as computed from contained workitems. The execution object passed as argument must be a ProjectActivity or a Milestone or a SummaryActivity or a ProjectPlan, otherwise a runtime exception is thrown.

Supported API: true

Parameters:

exec_obj -

Returns:

MonitorInfo

Throws:

WTException

getSubscribers

public Enumeration getSubscribers(ExecutionObject exec_obj,
                                  ProjectEventType event)
                           throws WTException

Get all subscribers for an event for the ExecutionObject passed as argument. The list of subscribers is returned as an enumeration.

Supported API: true

Parameters:

exec_obj -

event -

Returns:

Enumeration

Throws:

WTException

getSubscriptions

public QueryResult getSubscriptions(ExecutionObject exec_obj,
                                    WTUser user)
                             throws WTException

Returns all ObjectSubscription directly associated with the ExecutionObject and the WTUser passed as arguments. If user is null all object's subscriptions are returned.

Supported API: true

Parameters:

exec_obj -

user -

Returns:

QueryResult

Throws:

WTException

isManager

public boolean isManager(ProjectPlan plan,
                         WTUser user)
                  throws WTException

Returns 'true' if a wt.or.WTUser is a manager of the project that owns the ProjectPlan passed as argument. Returns 'false' otherwise.

Supported API: true

Parameters:

plan -

user -

Returns:

boolean

Throws:

WTException

removeDeliverable

public DeliverableHolder removeDeliverable(DeliverableHolder holder,
                                           Deliverable deliverable)
                                    throws WTException

Removes deliverable to execution object. Updates execution object status that have been changed because of the removal.

Supported API: true

Parameters:

holder -

deliverable -

Returns:

DeliverableHolder

Throws:

WTException

rollUpValues

public ExecutionObject rollUpValues(ExecutionObject exec_obj,
                                    ExecutionConfiguration roll_up_attrs)
                             throws WTException

Computes and sets dynamic values of the execution object. The dynamic values are the health status, the percent complete, the estimated finish date, the total work and the total cost. The computation is based on the values of the contained objects. If the recomputed value is different from the current one, the new values are propagated up the containment hierarchy.

The method allows the rolling up of specific attributes. This is accomplished by setting appropriate attributes in the ExecutionConfiguration passed as argument. For example, to roll up just the status and work of an activity, while keeping all other values the same (whether rolled up or overridden), use the following steps. ExecutionConfiguration config = new ExecutionConfiguration (0L); config.setRollUpStatus (true); config.setRollUpWork (true); activity = (ProjectActivity) ProjMonitorHelper.service.rollUpValues (activity, config);

Notes

• The ExecutionConfiguration constructor is passed 0L as argument. This means that all flags are set to 'false'. The remaining codes sets exactly those attributes that a roll up is desired.
• As a consequence of the operation, all rolled up flags are set to 'true'.
• If the ExecutionConfiguration passed as argument is null all attributes are rolled up.

Supported API: true

Parameters:

exec_obj -

roll_up_attrs -

Returns:

ExecutionObject

Throws:

WTException

rollUpValues

public ExecutionObject rollUpValues(ExecutionObject exec_obj)
                             throws WTException

Computes and sets dynamic values of the execution object. The dynamic values are the health status, the percent complete, the total work and the total cost. The computation is based on the values of the contained objects. If the recomputed value is different from the current one. The new values are not propagated up the containment hierarchy. This is the responsibility of the client code. Also if the execution object passed as argument is closed (COMPLETED or CANCELLED), then the values are not computed and taken as they are.

This method differs from the othe rollUpValues in 2 additional aspects. First all dynamic values are recomputed and, second, the method recursively computes the dynamic values of the contained objects. This method can be used to make sure that all dynamic values are consistent. In this aspect it is particularly useful in batch operations, when all propagation made only once, after all changes are performed.

Supported API: false

Parameters:

exec_obj -

Returns:

ExecutionObject

Throws:

WTException

subscribe

public void subscribe(ExecutionObject exec_obj,
                      ProjectEventType event,
                      Vector subscribers,
                      String msg)
               throws WTException

Create ObjectSubscription objects for an event for a given object. The list of subscribers is passed as a Vector, where each element can either be a principal or a reference to a principal.

Supported API: true

Parameters:

exec_obj -

event -

subscribers -

msg -

Throws:

WTException

unsubscribe

public void unsubscribe(ExecutionObject exec_obj,
                        ProjectEventType event,
                        Vector subscribers)
                 throws WTException

Delete ObjectSubscription for an event and a given object. The list of subscribers is passed as a Vector, where each element can either be a principal or a reference to a principal.

Supported API: true

Parameters:

exec_obj -

event -

subscribers -

Throws:

WTException

subscribe

public void subscribe(ExecutionObject exec_obj,
                      ProjectEventType event,
                      Vector subscribers,
                      String msg,
                      String attr_name,
                      String attr_value,
                      String key)
               throws WTException

Create ObjectSubscription objects for an event for a given object. The list of subscribers is passed as a Vector, where each element can either be a principal or a reference to a principal. This is used with Owner / PM Subscriptions where atribute name/value and key is needed

Supported API: false

Parameters:

exec_obj -

event -

subscribers -

msg -

attr_name -

attr_value -

key -

Throws:

WTException

unsubscribe

public void unsubscribe(ExecutionObject exec_obj,
                        ProjectEventType event,
                        Vector subscribers,
                        String msg,
                        String attr_name,
                        String attr_value,
                        String key)
                 throws WTException

Create ObjectSubscription objects for an event for a given object. The list of subscribers is passed as a Vector, where each element can either be a principal or a reference to a principal. This is used with Owner / PM Subscriptions where atribute name/value and key is needed

Supported API: false

Parameters:

exec_obj -

event -

subscribers -

msg -

attr_name -

attr_value -

key -

Throws:

WTException