001 /*
002 * file Feedback.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * (c) Copyright IBM Corporation 2004, 2008. All Rights Reserved.
008 * Note to U.S. Government Users Restricted Rights: Use, duplication or
009 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
010 */
011 package javax.wvcm;
012
013 import javax.wvcm.PropertyRequestItem.PropertyRequest;
014 import javax.wvcm.WvcmException.ReasonCode;
015
016 /**
017 * Provides feedback on the status of a long-running method.
018 * The feedback takes the form of an indication of what Resources have been modified,
019 * and an estimate of what percentage of the work being done by the method has been completed.
020 * The feedback interface also allows the caller of the method to request that the method be aborted.
021 *
022 * Note that a client cannot count on any notify method in the Feedback interface being invoked,
023 * so a resource might be changed without notifyIsModified being invoked, and
024 * work might have been completed without notifyPercentComplete or notifyActive ever being invoked.
025 *
026 * @since 1.0
027 */
028 public interface Feedback {
029
030 /**
031 * Called by the method to determine what properties to include in the result
032 * of the operation.
033 * The value of {@link #getPropertyRequestForModified} is initialized
034 * when the Feedback object is created and is never changed.
035 *
036 * @return the list of properties that the client wants to be available
037 * in the result of the operation.
038 * If this method returns null, only the {@link Resource#RESOURCE_IDENTIFIER}
039 * property is retrieved.
040 */
041 public PropertyRequest getPropertyRequestForResult();
042
043 /**
044 * Called by the method to indicate that the specified resource has been modified by the method.
045 * This is primarily intended to be used by a GUI client, so that the client can update its display
046 * of resources that have been modified by the method.
047 * This function may be called multiple times during the execution of the method,
048 * usually indicating that the specified resource has been modified more than once by the method.
049 *
050 * @param resource a resource that has been modified by the task. The resource must not be null.
051 */
052 public void notifyIsModified(Resource resource);
053
054 /**
055 * Called by the method to determine what properties to include in the argument to
056 * {@link #notifyIsModified}.
057 * The value of {@link #getPropertyRequestForModified} is initialized when the Feedback object
058 * is created and is never changed.
059 * To avoid overloading the server, the client should limit this property list
060 * to the minimum set of properties needed to identify whether the resource is
061 * currently being displayed in the client GUI, and the client would then use
062 * {@link Resource#doReadProperties} to retrieve the information necessary to
063 * update the GUI for those resources that are currently being displayed.
064 *
065 * @return the list of properties that the client wants to be available
066 * in the resource argument of {@link #notifyIsModified}.
067 * If this is null, no modification notifications are generated.
068 */
069 public PropertyRequest getPropertyRequestForModified();
070
071 /**
072 * Called by the method to indicate the specified percentage of the work is complete.
073 * Note that there is no guarantee that this accurately reflects the amount of work completed.
074 *
075 * @param percentComplete a value between 0 and 100, where 100 means the work is complete.
076 */
077 public void notifyPercentComplete(int percentComplete);
078
079 /**
080 * Format a message, using {@link java.text.MessageFormat} conventions
081 *
082 * @param message a message that could be presented to a user. The message may be null.
083 * @param arguments objects to replace the {0},{1}, ... patterns in the message.
084 */
085 public String format(String message, Object... arguments);
086
087 /**
088 * Called by the method to indicate work is progressing,
089 * but that it cannot estimate what percentage is completed.
090 *
091 * @param message a message that could be presented to a user.
092 */
093 public void notifyActive(String message);
094
095 /**
096 * Called by the method to indicate a warning.
097 *
098 * @param message a message that describes an anomalous situation.
099 */
100 public void notifyWarning(String message);
101
102 /**
103 * Called by the method to determine whether the client has requested that the method be aborted.
104 * The Feedback object must provide a mechanism for the client to request that a method be aborted,
105 * such as defining a requestAbort() method on the Feedback object that a thread in the client can invoke.
106 * If the method aborted because isAbortRequested() was true, the method must throw WvcmException
107 * with a {@link ReasonCode#ABORTED} ReasonCode.
108 * Note that when a client has requested that a method be aborted,
109 * there is no guarantee that the method will actually abort.
110 * It may instead complete successfully, or it may fail for a different reason, as indicated by
111 * throwing WvcmException with a reason code other than {@link ReasonCode#ABORTED}.
112 *
113 * @return true if the client has requested that the method be aborted.
114 */
115 public boolean isAbortRequested();
116
117 /**
118 * Create a Feedback object like this Feedback object
119 * but with no result property request and no progress notification.
120 */
121 public Feedback nest();
122
123 /**
124 * Create a Feedback object like this Feedback object
125 * but with the specified property request and no progress notification.
126 */
127 public Feedback nest(PropertyRequest propertyRequest);
128
129 /**
130 * Create a Feedback object like this Feedback object for sub-progress notification
131 * but with a null resultPropertyRequest.
132 * @return a Feedback object like this Feedback object for sub-progress notification
133 * but with a null resultPropertyRequest.
134 */
135 public Feedback nest(int percentCompleted);
136
137 /**
138 * Create a Feedback object like this Feedback object for sub-progress notification,
139 * but with the specified resultPropertyRequest.
140 * @return a Feedback object like this Feedback object for sub-progress notification,
141 * but with the specified resultPropertyRequest.
142 */
143 public Feedback nest(PropertyRequest resultPropertyRequest, int percentCompleted);
144
145 }