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