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 * (C) Copyright IBM Corporation 2008, 2011.  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
014package com.ibm.rational.wvcm.stp.cc;
015
016import 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 */
031public 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 CcClearPromptCallback#promptForProceed(String, ProceedOrAbort, List, MsgType)} method.
042     */
043    public enum ProceedOrAbort {
044        PROCEED, ABORT
045    }
046
047    /**
048     * Possible responses for {@link CcClearPromptCallback#promptForYesOrNo(String, YesOrNo, List, MsgType)} 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 defaultChoice 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}