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 */
011package javax.wvcm;
012
013import javax.wvcm.PropertyRequestItem.PropertyRequest;
014import 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 */
028public 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}