001    /*
002     * file CqDynamicChoiceList.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cq.CqDynamicChoiceList
008     *
009     * © Copyright IBM Corporation 2004, 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.cq;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import java.util.List;
019    
020    import javax.wvcm.WvcmException;
021    import javax.wvcm.PropertyNameList.PropertyName;
022    
023    import com.ibm.rational.wvcm.stp.StpResource;
024    import com.ibm.rational.wvcm.stpex.StpExBase;
025    
026    /**
027     * A proxy for a ClearQuest dynamic choice list.
028     *  * <p>
029     * The user-friendly specification for the location of a dynamic choice list has the form
030     * <pre>
031     *  <b>cq.choicelist:</b><i>&lt;choice-list-name&gt;</i>@<i>&lt;db-set&gt;</i>/<i>&lt;user-db&gt;</i>
032     * </pre>
033     */
034    public interface CqDynamicChoiceList 
035        extends CqContextResource {
036        
037        /** The list of choices in this dynamic choice list */
038        public static final PropertyName<List<String>> MEMBER_LIST =
039            new PropertyName<List<String>>(PROPERTY_NAMESPACE, "member-list");
040    
041        /**
042         * Returns the value of the {@link #MEMBER_LIST MEMBER_LIST} property as
043         * defined by this proxy. If this property was set in the proxy via
044         * {@link #setMemberList(List, List)}, only the list of additions will be
045         * returned
046         * 
047         * @return A list of Strings each representing one member of the choice list
048         * 
049         * @throws WvcmException if this proxy does not define a value for the
050         *             {@link #MEMBER_LIST MEMBER_LIST} property.
051         */
052        public List<String> getMemberList() throws WvcmException;
053    
054        /**
055         * Defines values for the {@link #MEMBER_LIST MEMBER_LIST} property of this
056         * proxy.
057         * 
058         * @param choices A list of Strings specifying the members of this dynamic
059         *            choice list. This list becomes the entire new content of the
060         *            dynamic choice list. In a highly collaborative environment,
061         *            updating the list in this fashion is discouraged. Use
062         *            {@link #setMemberList(List, List)} instead.
063         */
064        public void setMemberList(List<String> choices);
065    
066        /**
067         * Establishes the values to be added to and/or deleted from the MEMBER_LIST
068         * property when that property is updated from this proxy (via
069         * doWriteProperties or any other "do" method of this interface).
070         * 
071         * @param additions The list of String values that must be in the
072         *            MEMBER_LIST property after it has been updated from this
073         *            proxy. Thus, it is OK for a value in this list to already be a
074         *            member of the property value. This list may be empty or null
075         *            if no values are to be added to the property. A value may not
076         *            appear in both this list and the deletions list.
077         * 
078         * @param deletions The list of String values that must not be in the
079         *            MEMBER_LIST property after it has been updated from this
080         *            proxy. Thus, it is OK for a value in this list to not be a
081         *            current member of the property value. This list may be empty
082         *            or null if no values are to be deleted from the property. A
083         *            value may not appear in both this list and the additions list.
084         */
085        void setMemberList(List<String> additions,
086                           List<String> deletions);
087    }