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 * (C) 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
014package com.ibm.rational.wvcm.stp.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.util.List;
019
020import javax.wvcm.WvcmException;
021import javax.wvcm.PropertyNameList.PropertyName;
022
023import com.ibm.rational.wvcm.stp.StpResource;
024import 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 */
034public 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}