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 }