001    /*
002     * file CcClearPromptCallback.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM
006     * 
007     * com.ibm.rational.wvcm.stp.cc.CcClearPromptCallback
008     *
009     * © Copyright IBM Corporation 2008.  All Rights Reserved. 
010     * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
011     * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
012     */
013    
014    package com.ibm.rational.wvcm.stp.cc;
015    
016    import java.util.List;
017    
018    /**
019     * <p>Interface for handling ClearPrompt user interaction requests.
020     * </p>
021     * <p>ClearCase trigger scripts may use ClearPrompt to interactively prompt the
022     * user for various kinds of input or responses.  CM API applications that wish
023     * to handle these ClearPrompt requests must implement this interface and
024     * register the implementation object with the ClearCase provider via
025     * <code>CcProvider.registerClearPromptCallback</code>.
026     * </p>
027     * <p>See the clearprompt manual page - <code>cleartool man clearprompt</code> -
028     * for more information.
029     * </p>
030     */
031    public interface CcClearPromptCallback {
032    
033        /**
034         * ClearPrompt message type.
035         */
036        public enum MsgType {
037            BOX, OK, WARNING, ERROR
038        }
039    
040        /**
041         * Possible responses for {@link #promptToProceed} method.
042         */
043        public enum ProceedOrAbort {
044            PROCEED, ABORT
045        }
046    
047        /**
048         * Possible responses for {@link #promptForYesOrNo} method.
049         */
050        public enum YesOrNo {
051            YES, NO, ABORT
052        }
053    
054        /**
055         * Callback methods may throw this exception to indicate that the user
056         * wishes to abort the current ClearCase operation - the operation that
057         * caused the trigger to fire.
058         */
059        public class AbortException extends Exception {
060        }
061    
062        /**
063         * Prompt the user for one or more lines of text.
064         * @param promptMsg Prompt message to display
065         * @param defaultResponse Default response to display
066         * @param multiLineOk Allow user to enter multiple lines
067         * @param maskInput Mask user input for password entry
068         * @return user's response string
069         * @exception AbortException to indicate the user wants to abort the
070         *            current ClearCase operation
071         */
072        public String 
073        promptForText(
074                String promptMsg,
075                String defaultResponse,
076                boolean multiLineOk,
077                boolean maskInput)
078        throws AbortException;
079    
080        /**
081         * Ask the user for a "yes" or "no" response to a question.
082         * @param promptMsg Prompt message to display
083         * @param defaultChoice Default response to display
084         * @param choices Optional subset of responses to display
085         * @param msgType message type: OK, WARNING, ERROR, BOX
086         * @return user's response: YES, NO, or ABORT
087         */
088        public YesOrNo 
089        promptForYesOrNo(
090                String promptMsg, 
091                YesOrNo defaultChoice,
092                List<YesOrNo> choices,
093                MsgType msgType);
094    
095        /**
096         * Ask the user whether to proceed with the current ClearCase operation
097         * or abort it.
098         * @param promptMsg Prompt message to display
099         * @param defaultResponse Default response to display
100         * @param choices Optional subset of responses to display
101         * @param msgType message type: OK, WARNING, ERROR, BOX
102         * @return user's response: PROCEED or ABORT
103         */
104        public ProceedOrAbort 
105        promptForProceed(
106                String promptMsg, 
107                ProceedOrAbort defaultChoice,
108                List<ProceedOrAbort> choices,
109                MsgType msgType);
110    
111        /**
112         * Ask the user to select a single item from a list of choices.
113         * @param promptMsg Prompt message to display
114         * @param choices Possible choices
115         * @return user's selection from list of possible choices
116         * @exception AbortException to indicate the user wants to abort the
117         *            current ClearCase operation
118         */
119        public String
120        promptForChoice(
121                String promptMsg,
122                List<String> choices)
123        throws AbortException;
124    
125        /**
126         * Ask the user to select zero or more items from a list of choices.
127         * @param promptMsg Prompt message to display
128         * @param choices Possible choices
129         * @return user's selection(s) from list of possible choices
130         * @exception AbortException to indicate the user wants to abort the
131         *            current ClearCase operation
132         */
133        public List<String>
134        promptForMultiChoice(
135                String promptMsg,
136                List<String> choices)
137        throws AbortException;
138    }