001    /*
002     * file StpActivity.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.StpActivity
008     *
009     * (C) Copyright IBM Corporation 2007, 2009.  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;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import javax.wvcm.WvcmException;
019    import javax.wvcm.PropertyNameList.PropertyName;
020    
021    import com.ibm.rational.wvcm.stp.cc.CcActivity;
022    import com.ibm.rational.wvcm.stp.cc.CcTypeBase.Scope;
023    import com.ibm.rational.wvcm.stp.cq.CqQuery;
024    import com.ibm.rational.wvcm.stp.cq.CqRecord;
025    import com.ibm.rational.wvcm.stpex.StpExEnumeration;
026    import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
027    
028    /**
029     * <p>
030     * StpActivity is an interface for a proxy which may represent one of these
031     * three cases:
032     * </p>
033     * <ul>
034     * <li>A UCM-enabled CQ record not bound to a UCM activity, or</li>
035     * <li>A UCM activity not bound to a CQ record, or</li>
036     * <li>A UCM-enabled CQ record-UCM activity pair (bound together)</li>
037     * </ul>
038     * <p>
039     * It serves two purposes:
040     * </p>
041     * <ul>
042     * <li>It provides access to properties which are common to all of the above
043     * three cases</li>
044     * <li>It provides a means to access the CcActivity and/or CqRecord proxies for
045     * the persistent UCM activity or CQ record resources involved in the above
046     * three cases</li>
047     * </ul>
048     * <p>
049     * Although this interface extends StpResource, it is an abstraction. There is
050     * no factory method for constructing an instance of StpActivity, specifically.
051     * Proxies that implement this interface may be constructed only by constructing
052     * a CcActivity or a CqRecord. The location of an StpActivity will be that of
053     * a CcActivity or a CqRecord.
054     */
055    public interface StpActivity extends StpResource {
056    
057        enum CqUcmIntegrationState implements StpExEnumeration {
058    
059            /**
060             * This is an unbound UCM activity in a non-ClearQuest-enabled project.
061             */
062            UNBOUND_CC_ACTIVITY,
063    
064            /**
065             * This is an unbound ClearQuest record.
066             */
067            UNBOUND_CQ_RECORD,
068    
069            /**
070             * This is a UCM-enabled CQ record and a UCM activity that are bound to
071             * each other.
072             */
073            BOUND_CC_ACTIVITY_CQ_RECORD_PAIR;
074        }
075    
076        /**
077         * This activity's CQ-UCM integration state
078         */
079        PropertyName<CqUcmIntegrationState> CQ_UCM_INTEGRATION_STATE =
080            new PropertyName<CqUcmIntegrationState>(PROPERTY_NAMESPACE,
081                                                    "cq-ucm-integration-state");
082    
083        /**
084         * Returns the value of this proxy's {@link #CQ_UCM_INTEGRATION_STATE}
085         * property.
086         * 
087         * @return this activity's CQ-UCM integration state
088         * @throws WvcmException if this proxy doesn't define a value for this
089         *             property.
090         */
091        CqUcmIntegrationState getCqUcmIntegrationState() throws WvcmException;
092    
093        /**
094         * The ClearCase activity to which this StpActivity is bound. In
095         * ClearQuest-enabled UCM projects, all UCM activities are bound and the
096         * value of this property will always be non-null. In non-CQ-enabled
097         * projects, the value of this property will always be <b>null</b>.
098         */
099        PropertyName<CcActivity> BOUND_CC_ACTIVITY =
100            new PropertyName<CcActivity>(PROPERTY_NAMESPACE, "bound-cc-activity");
101    
102        /**
103         * Returns the value of this proxy's {@link #BOUND_CC_ACTIVITY} property.
104         * 
105         * @return this activity's bound CQ record, or <b>null</b> if thi activity
106         *         is not bound to a CcActivity
107         * @throws WvcmException if this proxy doesn't define a value for this
108         *             property.
109         */
110        CcActivity getBoundCcActivity() throws WvcmException;
111    
112        /**
113         * The ClearQuest record to which this UCM activity is bound. In
114         * ClearQuest-enabled UCM projects, all UCM activities are bound and the
115         * value of this property will always be non-null. In non-CQ-enabled
116         * projects, the value of this property will always be <b>null</b>.
117         */
118        PropertyName<CqRecord> BOUND_CQ_RECORD =
119            new PropertyName<CqRecord>(PROPERTY_NAMESPACE, "bound-cq-record");
120    
121        /**
122         * Returns the value of this proxy's {@link #BOUND_CQ_RECORD} property.
123         * 
124         * @return this activity's bound CQ record, or <b>null</b> if activity is
125         *         not bound to a CQ record.
126         * @throws WvcmException if this proxy doesn't define a value for this
127         *             property.
128         */
129        CqRecord getBoundCqRecord() throws WvcmException;
130    
131        /**
132         * A descriptive string - not necessarily unique - used to identify
133         * this activity when it appears in a GUI or in a report.
134         */
135        PropertyName<String> HEADLINE =
136            new PropertyName<String>(PROPERTY_NAMESPACE, "headline");
137    
138        /**
139         * Returns the value of this proxy's {@link #HEADLINE} property.
140         * 
141         * @return A String containing the description of this StpActivity
142         * @throws WvcmException if this proxy doesn't define a value for this
143         *             property.
144         */
145        String getHeadline() throws WvcmException;
146    
147        /**
148         * Defines a new value for the {@link #HEADLINE} property of this proxy.
149         * 
150         * @param headline The new headline string. Must not be <b>null</b>.
151         */
152        void setHeadline(String headline);
153    
154        /**
155         * @deprecated 
156         * Use {@link #ID_SELECTOR} for a unique string to identify
157         * this activity.
158         * <br>
159         * Use {@link javax.wvcm.Resource#DISPLAY_NAME} for the activity name.
160         */
161        PropertyName<String> ID =
162            new PropertyName<String>(PROPERTY_NAMESPACE, "id");
163    
164        /**
165         * @deprecated
166         */
167        String getId() throws WvcmException;
168        
169        /**
170         * A unique string to identify this activity.
171         */
172        PropertyName<String> ID_SELECTOR =
173            new PropertyName<String>(PROPERTY_NAMESPACE, "id-selector");
174        
175        /**
176         * Returns the value of this proxy's {@link #ID_SELECTOR} property.
177         * 
178         * @return A String containing the unique identifier for this StpActivity
179         * @throws WvcmException if this proxy doesn't define a value for this
180         *             property.
181         */
182        String getIdSelector() throws WvcmException;
183    }