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    }