Project: stp

javax.wvcm
Interface Feedback

All Known Implementing Classes:
DetailedFeedback, DetailedFeedback.NestedDetailedFeedback, PropertyRequestItem.PropertyRequest

public interface Feedback

Provides feedback on the status of a long-running method. The feedback takes the form of an indication of what Resources have been modified, and an estimate of what percentage of the work being done by the method has been completed. The feedback interface also allows the caller of the method to request that the method be aborted. Note that a client cannot count on any notify method in the Feedback interface being invoked, so a resource might be changed without notifyIsModified being invoked, and work might have been completed without notifyPercentComplete or notifyActive ever being invoked.

Since:
1.0

Method Summary
 String format(String message, Object... arguments)
          Format a message, using MessageFormat conventions
 PropertyRequestItem.PropertyRequest getPropertyRequestForModified()
          Called by the method to determine what properties to include in the argument to notifyIsModified(javax.wvcm.Resource).
 PropertyRequestItem.PropertyRequest getPropertyRequestForResult()
          Called by the method to determine what properties to include in the result of the operation.
 boolean isAbortRequested()
          Called by the method to determine whether the client has requested that the method be aborted.
 Feedback nest()
          Create a Feedback object like this Feedback object but with no result property request and no progress notification.
 Feedback nest(int percentCompleted)
          Create a Feedback object like this Feedback object for sub-progress notification but with a null resultPropertyRequest.
 Feedback nest(PropertyRequestItem.PropertyRequest propertyRequest)
          Create a Feedback object like this Feedback object but with the specified property request and no progress notification.
 Feedback nest(PropertyRequestItem.PropertyRequest resultPropertyRequest, int percentCompleted)
          Create a Feedback object like this Feedback object for sub-progress notification, but with the specified resultPropertyRequest.
 void notifyActive(String message)
          Called by the method to indicate work is progressing, but that it cannot estimate what percentage is completed.
 void notifyIsModified(Resource resource)
          Called by the method to indicate that the specified resource has been modified by the method.
 void notifyPercentComplete(int percentComplete)
          Called by the method to indicate the specified percentage of the work is complete.
 void notifyWarning(String message)
          Called by the method to indicate a warning.
 

Method Detail

format

String format(String message,
              Object... arguments)
Format a message, using MessageFormat conventions

Parameters:
message - a message that could be presented to a user. The message may be null.
arguments - objects to replace the {0},{1}, ... patterns in the message.

getPropertyRequestForModified

PropertyRequestItem.PropertyRequest getPropertyRequestForModified()
Called by the method to determine what properties to include in the argument to notifyIsModified(javax.wvcm.Resource). The value of getPropertyRequestForModified() is initialized when the Feedback object is created and is never changed. To avoid overloading the server, the client should limit this property list to the minimum set of properties needed to identify whether the resource is currently being displayed in the client GUI, and the client would then use Resource.doReadProperties(javax.wvcm.Feedback) to retrieve the information necessary to update the GUI for those resources that are currently being displayed.

Returns:
the list of properties that the client wants to be available in the resource argument of notifyIsModified(javax.wvcm.Resource). If this is null, no modification notifications are generated.

getPropertyRequestForResult

PropertyRequestItem.PropertyRequest getPropertyRequestForResult()
Called by the method to determine what properties to include in the result of the operation. The value of getPropertyRequestForModified() is initialized when the Feedback object is created and is never changed.

Returns:
the list of properties that the client wants to be available in the result of the operation. If this method returns null, only the Resource.RESOURCE_IDENTIFIER property is retrieved.

isAbortRequested

boolean isAbortRequested()
Called by the method to determine whether the client has requested that the method be aborted. The Feedback object must provide a mechanism for the client to request that a method be aborted, such as defining a requestAbort() method on the Feedback object that a thread in the client can invoke. If the method aborted because isAbortRequested() was true, the method must throw WvcmException with a WvcmException.ReasonCode.ABORTED ReasonCode. Note that when a client has requested that a method be aborted, there is no guarantee that the method will actually abort. It may instead complete successfully, or it may fail for a different reason, as indicated by throwing WvcmException with a reason code other than WvcmException.ReasonCode.ABORTED.

Returns:
true if the client has requested that the method be aborted.

nest

Feedback nest()
Create a Feedback object like this Feedback object but with no result property request and no progress notification.


nest

Feedback nest(int percentCompleted)
Create a Feedback object like this Feedback object for sub-progress notification but with a null resultPropertyRequest.

Returns:
a Feedback object like this Feedback object for sub-progress notification but with a null resultPropertyRequest.

nest

Feedback nest(PropertyRequestItem.PropertyRequest propertyRequest)
Create a Feedback object like this Feedback object but with the specified property request and no progress notification.


nest

Feedback nest(PropertyRequestItem.PropertyRequest resultPropertyRequest,
              int percentCompleted)
Create a Feedback object like this Feedback object for sub-progress notification, but with the specified resultPropertyRequest.

Returns:
a Feedback object like this Feedback object for sub-progress notification, but with the specified resultPropertyRequest.

notifyActive

void notifyActive(String message)
Called by the method to indicate work is progressing, but that it cannot estimate what percentage is completed.

Parameters:
message - a message that could be presented to a user.

notifyIsModified

void notifyIsModified(Resource resource)
Called by the method to indicate that the specified resource has been modified by the method. This is primarily intended to be used by a GUI client, so that the client can update its display of resources that have been modified by the method. This function may be called multiple times during the execution of the method, usually indicating that the specified resource has been modified more than once by the method.

Parameters:
resource - a resource that has been modified by the task. The resource must not be null.

notifyPercentComplete

void notifyPercentComplete(int percentComplete)
Called by the method to indicate the specified percentage of the work is complete. Note that there is no guarantee that this accurately reflects the amount of work completed.

Parameters:
percentComplete - a value between 0 and 100, where 100 means the work is complete.

notifyWarning

void notifyWarning(String message)
Called by the method to indicate a warning.

Parameters:
message - a message that describes an anomalous situation.

Generated Thu 18-Feb-2010 12:40 PM

Copyright © IBM 2010. All rights reserved.